Logistics API Document​

Enquiry and Notice / Download Logistics Reconciliation File

Introduction

Note: This API is currently not available.

This API allows merchants to query and download reconciliation reports in CSV format. The report includes information such as disbursements for logistics cash-on-delivery (COD) payments and deductions for logistics service fees. In addition to the CSV file, the API also returns a JSON response.

Application Flow

This API uses a paginated response mechanism. The query results are sorted by the order creation time from newest to oldest. The following describes the API call procedure:

  • Step 1: Execute the first API call, specify the number of records to be returned per page – [PageSize], and set the page number to 1 – [PageNo], which will return the total number of records – [TotalCount] from the response.
  • Step 2: Based on the total number of records – [TotalCount] obtained in Step 1 and the desired page size, determine the number of API calls required.
  • For example: When TotalCount = 300 and the page size is 100 records per page, 3 API calls are needed to retrieve all 300 records (as shown in the table below).

API URLs

  • Stage：https://logistics-stage.ecpay.com.tw/Helper/QueryCheckAccounts
  • Production：https://logistics.ecpay.com.tw/Helper/QueryCheckAccounts

HTTPS Transfer Protocol

  • Accept：text/html
  • Content Type：application/x-www-form-urlencoded
  • HTTP Method：POST

Request Parameter Description

PlatformID String(10)

  • Provided by ECPAY, this parameter is used by Platform. General merchant should set this to null.
  • When used by Platform, please use the MerchantID bound with merchant account

MerchantID String(10)
Required

Merchant ID (provided by Green World).

PageSize Int
Required

The API query results are returned in a paginated format. This parameter is used to set the number of records returned per page.

❗ Special Note：

To ensure system performance and response time, the maximum number of records per page is limited to 300.

PageNo Int
Required

The number of records returned by the API is determined by the [PageSize] parameter.

If the total number of records exceeds the specified value, multiple API calls are required to retrieve all data. Additionally, the [PageNo] parameter can be used to specify which page of results to return.

For example: If [PageSize] is set to 100 and [PageNo] is set to 2, the response will contain order records 101 to 200.

❗ Special Note：

The query results will be sorted by date, from the most recent to the oldest, based on the date type specified by the [SearchType] parameter.

DataType Int

Response Data Format

  • 1: JSON (default)
  • 2: CSV

SearchType String(1)
Required

Specifies the date type for filtering the query results:

  • 1：Order Created Date
  • 2：Logistics Fee Deduction Date
  • 3：Logistics Collection Remittance Date
  • 4：Return Charge Deduction Date

StartDate String(10)
Required

Start Date for Query

  • The date format is “yyyy/MM/dd”.
  • The query range cannot exceed 3 months.

EndDate String(10)
Required

End Date for Query

  • The date format is “yyyy/MM/dd”.
  • The query range cannot exceed 3 months.

LogisticsType String(20)

Logistics Type

  • CVS: Convenience Store Pickup (including B2C and C2C)
  • HOME: Home Delivery
  • If querying for all types, please omit this parameter.

LogisticsSubType String(20)

Logistics subtype.
B2C

  • FAMI: Family Mart
  • UNIMART: 7-ELEVEN
  • HILIFE: Hi-Life
  • UNIMARTFREEZE: refrigeration transportation of 7-ELEVEN

C2C

  • FAMIC2C: Family Mart store to store
  • UNIMARTC2C: 7-ELEVEN store to store
  • HILIFEC2C: Hi-Life store to store
  • OKMARTC2C:OK store to store

❗ Special Note：

  • If querying for all types, please omit this parameter.

CheckMacValue String
Required

Checksum, Please refer to the appendix for more information on checksum mechanism.

❗ Special Note：

  • When the parameter [DataType] is set to 1, the response data will be in JSON format.

Response Parameter Description (JSON)

RtnCode Int

Response codes to indicate whether the API is successfully executed or not.

  • 1: API is successfully executed.
  • Others: failed.
  • For more details please see error codes.

RtnMsg String(200)

Response messages

TotalCount Int

This parameter represents the total number of records matching the query conditions.

PageNo Int

This parameter indicates the current page number being returned in the query result.

LogisticsData Array[Object]

Logistics Order Data

TradeDate String(20)

Indicates the order created time. The format is yyyy/MM/dd HH:mm:ss.

MerchantTradeNo String(20)

The order number assigned by the merchant.

AllPayLogisticsID String(20)

The logistics order number assigned by ECPay.

MerchantID String(9)

Merchant ID

GoodsAmount Int

The amount or price of the product.

ReceiverName String

The name of the recipient.

ReceiverPhone String(20)

The landline number of the recipient.

ReceiverCellPhone String(10)

The mobile phone number of the recipient.

LogisticsType String(20)

Logistics Type

Please refer to the List of Logistics Type and Logistics Subtype.

LogisticsSubType String(20)

Logistics Subtype

Please refer to the List of Logistics Type and Logistics Subtype.

IsCollection String(1)

Cash on Delivery (COD) Status

  • N: Delivery only, no cash on delivery.
  • Y: Cash on delivery (COD).

Temperature String(4)

Temperature Level

  • 0001: Ambient (Room Temperature)
  • 0002: Refrigerated
  • 0003: Frozen

Specification String(4)

Home Delivery Item Size Specifications

These specifications will only be returned when the logistics type is HOME.

  • 0001: 60 cm
  • 0002: 90 cm
  • 0003: 120 cm
  • 0004: 150 cm

LogisticsStatus String(8)

Logistics Status

Please refer to Shipment Status.

ShipmentNo String(25)

Delivery Number

  • This will be returned only when the logistics type is CVS.
  • For convenience store B2C delivery, please refer to this field.

BookingNote String(50)

Shipment Tracking Number

  • This will be returned only when the logistics type is HOME.

CVSPaymentNo String(15)

Sender’s Shipment Number

  • This will be returned only when the logistics type is CVS.
  • For convenience store C2C delivery, please use this field. For 7-ELEVEN, the shipment number should be combined with the [CVSValidationNo] to generate the tracking number.

CVSValidationNo String(10)

Verification Code

This will be returned only when the logistics subtype is UNIMARTC2C.

❗ Special Note：

DeliveryDate String(10)

Delivery to Store Date

  • The format is: yyyy/MM/dd

GoodsWeight Number

Product Weight

  • This will be returned only when the logistics subtype [LogisticsSubType] is POST (Chunghwa Post).
  • The maximum weight is 20 kilograms, and the weight is displayed up to 3 decimal places.
  • The unit is kilograms (kg).

ActualWeight Number

Actual Weight

  • This will be returned only when the logistics subtype [LogisticsSubType] is POST (Chunghwa Post).
  • The maximum weight is 20 kilograms, and the weight is displayed up to 3 decimal places.
  • The unit is kilograms (kg).

InitShipCharge Int

Initial Logistics Fee

ActualShipCharge Int

Actual Logistics Fee

ExtraChargeFee Int

Additional Charge

FeeHoldStatus Int

Held Payment for Logistics Fee

  • 1: Payment on hold
  • 2: Returned

ShipChargeDate String(10)

Logistics Fee Charge Date

  • The format is: yyyy/MM/dd

CollectionAmount Int

Logistics Collection Amount

CollectionChargeFee Int

Logistics Collection Fee

CollectionAllocateAmount Int

Logistics Collection Disbursement Amount

❗ Special Note：

When the returned value is 0, it does not necessarily mean that the disbursement amount is zero. The following are two possible scenarios:

  1. If the Collection Amount [CollectionAmount] is greater than 0, and the Logistics Collection Disbursement Date [CollectionAllocateDate] is empty, it means the payment has not yet been disbursed.
  2. If the Collection Amount [CollectionAmount] is 0, it indicates that the order is not a Cash on Delivery (COD) transaction.

CollectionAllocateDate String(10)

Logistics Collection Disbursement Date

  • The format is: yyyy/MM/dd

SenderStoreId String(10)

Sender Store ID

  • Only returned when the LogisticsType is CVS.

SenderStoreName String(40)

Sender Store Name

  • Only returned when the LogisticsType is CVS.

ReceiverStoreId String(10)

Receiver Store ID

  • Only returned when the LogisticsType is CVS.

ReceiverStoreName String(40) 

Receiver Store Name

  • Only returned when the LogisticsType is CVS.

ReturnRecvStoreId String(10)

Return Store ID

The store ID of the convenience store where the returned item was processed.

  • Only returned when the LogisticsSubType is C2C.

ReturnRecvStoreName String(40)

Return Store Name

The store Name of the convenience store where the returned item was processed.

  • Only returned when the LogisticsSubType is C2C.

ReturnShipCharge Int

Return Shipping Fee

Charged when a package requiring payment upon delivery is returned to the seller due to the buyer not picking it up or refusing the delivery.

ReturnChargeFee Int

Return Processing Fee

Charged when a cash-on-delivery package is returned to the seller because the buyer failed to pick it up or refused the delivery.

ReturnShipChargeDate String(10)

The charge deduction date for the return shipping fee and return processing fee.

❗ Special Note：

  • When the parameter [DataType] is set to 2, the response will be a CSV file.

Response Parameter Description (CSV)

訂單時間

The format is: yyyy/MM/dd HH:mm:ss

廠商訂單編號

綠界物流訂單編號

商店代號

訂單金額

收件人姓名

收件人手機 / 市話

物流廠商

Logistics Type

Please refer to the List of Logistics Type and Logistics Subtype.

服務名稱

  • 超商門市寄/取貨
    Convenience Store Drop-off/Pick-up

  • 大宗寄倉超商取貨
    Bulk Warehouse Drop-off at Convenience Store

  • 宅配
    Home Delivery

純配送 / 貨到付款

  • 純配送
    Standard Delivery

  • 貨到付款
    Cash on Delivery (COD)

溫層

  • 常溫
    Room Temperature

  • 冷藏
    Refrigerated

  • 冷凍
    Frozen

宅配規格(長+寬+高)

物流狀態

Logistics Status

Please refer to Shipment Status.

配送編號 / 托運單號

交貨便代碼 / 店到店編號

到店日期

The format is:yyyy/MM/dd

商品重量

實際重量

初始物流運費

實際物流運費

加價費用

圈存狀態

Held Payment for Logistics Fee

  • 保留中
    Payment on hold
  • 已歸還
    Returned

物流費扣款日期

The format is: yyyy/MM/dd

物流代收款項

物流代收手續費率

物流代收手續費

物流代收款項撥款金額

Logistics Collection Disbursement Amount

❗ Special Note：

When the Logistics Collection Disbursement Amount is 0, the following two scenarios do not indicate that the disbursement amount is 0:

  1. If the collection amount is greater than 0 and the Logistics Collection Disbursement Date is missing, it means the funds have not been disbursed yet.
  2. If the collection amount is 0, it means the order does not require a cash on delivery payment.

物流代收款項撥款日期

The format is: yyyy/MM/dd

備註

寄件門市代碼

寄件門市名稱

收件門市代碼

收件門市名稱

退貨門市代碼

Return Store ID

The store ID of the convenience store where the returned item was processed.

  • Only returned when the LogisticsSubType is C2C.

退貨門市名稱

Return Store Name

The store Name of the convenience store where the returned item was processed.

  • Only returned when the LogisticsSubType is C2C.

退回運費

Return Shipping Fee

Charged when a package requiring payment upon delivery is returned to the seller due to the buyer not picking it up or refusing the delivery.

退回手續費

Return Processing Fee

Charged when a cash-on-delivery package is returned to the seller because the buyer failed to pick it up or refused the delivery.

退回費扣款日期

The charge deduction date for the return shipping fee and return processing fee.

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

Green World