全方位物流服務API技術文件 / 下載物流對帳檔

應用場景：

※目前尚未開放

提供特店查詢及下載對帳報表CSV檔，透過此API可取得物流代收款項之撥款以及物流運費扣款等資訊。

應用流程

此API採分頁顯示的回傳機制，查詢結果會依照訂單建立時間由新到舊進行排序，以下說明API呼叫步驟程序：

Step1. 執行第一次API呼叫，設定每頁回傳筆數-[PageSize]及設定顯示的頁數-[PageNo，固定帶1]，即取得綠界回應的資料總筆數-[TotalCount]。

Step2. 根據Step1取得的資料總筆數-[TotalCount]，以及所需的分頁筆數來決定API的查詢次數

例如：當TotalCount=300，分頁需求為每頁100筆，則需呼叫3次取回所有資料(如下表所示)

API 呼叫	[PageNo] 參數值	[PageSize] 參數值
第一次	1	100
第二次	2	100
第三次	3	100

API介接網址：

測試環境：https://logistics-stage.ecpay.com.tw/Express/v2/QueryCheckAccounts
正式環境：https://logistics.ecpay.com.tw/Express/v2/QueryCheckAccounts

HTTPS 傳輸協定

Content Type ：application/json
HTTP Method ：POST

特店傳入參數(JSON格式)

PlatformID String(10)
特約合作平台商代號

PlatformID為與綠界有合作專案的特約平台商身分使用。一般特店或賣家身分(Merchant)，或平台商本身，此參數請帶放空值。
若隸屬於特約平台商的一般特店，此參數請帶放平台商的MerchantID。

MerchantID String(10)
特店編號 必填

RqHeader Object
傳入資料 必填

Timestamp String(10)
傳入時間 必填

請將傳輸時間轉換為時間戳(GMT+8)，綠界會利用此參數將當下的時間轉為Unix TimeStamp來驗證此次介接的時間區間。

注意事項：

驗證時間區間為 5 分鐘內有效，若超過此驗證時間則此次訂單將無法建立，產生時間戳請參考相關資料。
合作特店須進行主機「時間校正」，避免主機產生時差，延伸API無法正常運作。

Data String
加密資料 必填

回傳相關資料，此為加密過JSON格式的資料。加密方法說明

特店傳入參數範例(JSON格式)

				
					{
    "MerchantID": "2000132",
    "RqHeader": {
        "Timestamp": "1525168923"
    },
    "Data": "加密資料"
}

Data參數說明(JSON格式)

MerchantID String(10)
廠商編號 必填

由綠界科技提供

PageSize Int
單頁顯示筆數

當 API 查詢回傳結果為 JSON 格式時，資料將以分頁方式回傳。
本參數用於設定每頁回傳的資料筆數。

注意事項：

為了保證系統效能和響應速度，單頁上限為300筆。
此參數僅於[DataType]=1，即回傳資料類型為JSON時有效。

PageNo Int
顯示的頁數

API 的回傳筆數依 [PageSize] 參數設定，若資料總量超過設定值，需透過多次查詢來取得完整資料。此外，可透過此參數指定要回傳的特定頁數。
例如：當 PageSize 設為 100 且 PageNo 設為 2 時，回傳結果將包含第 101 至第 200 筆訂單資料。

注意事項：

查詢結果會根據[SearchType]設定的日期類別，按照日期時間較新排列至較舊的。
此參數僅於[DataType]=1，即回傳資料類型為JSON時有效。

DataType Int
回傳資料類型 必填

Response回傳的資料類型

1：JSON
2：CSV

SearchType String(1)
查詢日期條件 必填

要查詢的日期條件

1：訂單成立日期
2：物流運費扣款日期
3：物流代收款項撥款日期
4：退回費扣款日期

StartDate String(10)
查詢開始日期 必填

查詢開始日期

日期格式為「yyyy/MM/dd」
查詢區間不可超過3個月

EndDate String(10)
查詢結束日期 必填

查詢結束日期

日期格式為「yyyy/MM/dd」
查詢區間不可超過3個月

LogisticsType String(20)
物流類型

CVS：超商取貨 (含B2C及C2C)
HOME：宅配
若查詢全部，請忽略此參數設定。

LogisticsSubType String(20)
物流子類型

大宗寄倉超商取貨(B2C)
FAMI：全家
UNIMART：7-ELEVEN超商
UNIMARTFREEZE：7-ELEVEN冷凍店取
HILIFE：萊爾富
超商門市寄/取貨(C2C)
FAMIC2C：全家店到店
UNIMARTC2C：7-ELEVEN超商交貨便
HILIFEC2C：萊爾富店到店
OKMARTC2C：OK店到店
宅配(HOME)
TCAT：黑貓
POST：中華郵政

注意事項：

若要查詢全部時，請忽略此一參數

Data參數範例

				
					{
    "MerchantID": "2000132",
    "PageSize": 100,
    "PageNo": 2,
    "DataType": "1",
    "SearchType": "1",
    "StartDate": "2024/10/01",
    "EndDate": "2024/10/31"
}

注意事項：當DataType=1時，回傳資料為JSON格式

綠界回傳參數說明(JSON格式)

PlatformID String(10)
特約合作平台商代號

PlatformID為與綠界有合作專案的特約平台商身分使用。一般特店或賣家身分(Merchant)，或平台商本身，此參數請帶放空值。
若隸屬於特約平台商的一般特店，此參數請帶放平台商的MerchantID。

MerchantID String(10)
特店編號

RpHeader Object
回傳資料

Timestamp String(10)
回傳時間

請將傳輸時間轉換為時間戳(GMT+8)，綠界會利用此參數將當下的時間轉為Unix TimeStamp來驗證此次介接的時間區間。

注意事項：

驗證時間區間為 5 分鐘內有效，若超過此驗證時間則此次訂單將無法建立，產生時間戳請參考相關資料。
合作特店須進行主機「時間校正」，避免主機產生時差，延伸API無法正常運作。

TransCode Int
回傳代碼

1 代表 API 傳輸資料(MerchantID, RqHeader, Data)接收成功，實際的 API 執行結果狀態請參考 RtnCode。

TransMsg String(200)
回傳訊息

回傳訊息

Data String
加密資料

回傳相關資料，此為加密過JSON格式的資料。加密方法說明

綠界回傳參數範例

				
					{
    "PlatformID": "",
    "MerchantID": "2000132",
    "RpHeader": {
        "Timestamp": "1525169058"
    },
    "TransCode": 1,
    "TransMsg": "",
    "Data": "加密資料"
}

回傳Data參數說明(JSON格式)

RtnCode Int
回應代碼

1 代表 API 執行成功，其餘代碼均為失敗，失敗代碼請參考交易訊息代碼表。

RtnMsg String(200)
回應訊息

TotalCount Int
總筆數

PageNo Int
目前顯示的頁數

LogisticsData Array[Object]
物流訂單資料

TradeDate String(20)
訂單成立時間

格式為：yyyy/MM/dd HH:mm:ss

MerchantTradeNo String(20)
廠商訂單編號

AllPayLogisticsID String(20)
綠界物流訂單編號

MerchantID String(9)
廠商編號

GoodsAmount Int
商品金額

ReceiverName String
收件人姓名

ReceiverPhone String(20)
收件人市話

ReceiverCellPhone String(10)
收件人手機

LogisticsType String(20)
物流類型

請參考物流方式一覽表

LogisticsSubType String(20)
物流子類型

請參考物流方式一覽表

IsCollection String(1)
是否代收貨款

N：純配送，無代收貨款
Y：貨到付款

Temperature String(4)
溫層

0001：常溫
0002：冷藏
0003：冷凍

Specification String(4)
規格

物流類型為HOME才會回傳

0001：60cm
0002：90cm
0003：120cm
0004：150cm

LogisticsStatus String(8)
物流狀態

請參考物流狀態代碼一覽表

ShipmentNo String(25)
配送編號

物流類型為CVS才會回傳
超商B2C配送編號請讀取此欄位

BookingNote String(50)
托運單號

物流類型為HOME才會回傳

CVSPaymentNo String(15)
寄貨編號

僅當物流類型為 CVS 時會回傳。
超商 C2C 配送編號請使用此欄位，其中 7-ELEVEN 的配送編號需結合 CVSValidationNo 組合生成。

CVSValidationNo String(10)
驗證碼

(C2C) 7-ELEVEN才會回傳

注意事項：7-ELEVEN C2C 交貨便代碼為CVSPaymentNo與CVSValidationNo組合而成。

DeliveryDate String(10)
到店日期

格式為：yyyy/MM/dd

GoodsWeight Number
商品重量

當物流子類型[LogisticsSubType]為POST(中華郵政)才會回傳
上限20公斤，最多顯示至小數3位
單位為公斤(kg)

ActualWeight Number
實際重量

當物流子類型[LogisticsSubType]為POST(中華郵政)才會回傳
上限20公斤，最多顯示至小數3位
單位為公斤(kg)

InitShipCharge Int
初始物流運費

當物流子類型[LogisticsSubType]為POST(中華郵政)才會回傳

ActualShipCharge Int
實際物流運費

ExtraChargeFee Int
加價費用

FeeHoldStatus Int
預扣物流費用圈存狀態

1：保留中
2：已歸還

ShipChargeDate String(10)
物流運費扣款日期

格式為：yyyy/MM/dd

CollectionAmount Int
物流代收款項

CollectionChargeFee Int
物流代收金額手續費

CollectionAllocateAmount Int
物流代收款項撥款金額

注意事項：

當回傳值為0元時，以下兩種情況不代表撥款金額為0元：

若代收金額[CollectionAmount]大於0，且物流代收款項撥款日期[CollectionAllocateDate]無資料，表示尚未撥款。
若代收金額[CollectionAmount]為0元，表示此筆為無代收貨款的訂單。

CollectionAllocateDate String(10)
物流代收款項撥款日期

格式為：yyyy/MM/dd

SenderStoreId String(10)
寄件門市代碼

當物流子類型[LogisticsSubType]為C2C才會回傳

SenderStoreName String(40)
寄件門市名稱

當物流子類型[LogisticsSubType]為C2C才會回傳

ReceiverStoreId String(10)
收件門市代碼

當物流類型[LogisticsType]為CVS才會回傳

ReceiverStoreName String(40)
收件門市名稱

當物流類型[LogisticsType]為CVS才會回傳

ReturnRecvStoreId String(10)
退貨門市代碼

當貨品退貨時，返回的超商門市代碼

當物流子類型[LogisticsSubType]為C2C才會回傳

ReturnRecvStoreName String(40)
退貨門市名稱

當貨品退貨時，返回的超商門市名稱

當物流子類型[LogisticsSubType]為C2C才會回傳

ReturnShipCharge Int
退回運費

當賣家寄出代收貨款包裹，因買家未取或拒收等因素，導致包裹退回賣家產生的運費。

當物流子類型[LogisticsSubType]為TCAT(黑貓)才會回傳

ReturnChargeFee Int
退回手續費

當賣家寄出代收貨款包裹，因買家未取或拒收等因素，導致包裹退回賣家產生的手續費。

當物流子類型[LogisticsSubType]為TCAT(黑貓)才會回傳

ReturnShipChargeDate String(10)
退回費扣款日期

退回運費及退回手續費的扣款日期

當物流子類型[LogisticsSubType]為TCAT(黑貓)才會回傳

Data參數範例

				
					{
    "RtnCode": 1,
    "RtnMsg": "成功",
    "TotalCount": 350,
    "PageNo": 2,
    "LogisticsData":[
        {
            "TradeDate": "2024/10/30 11:00:42",
            "MerchantTradeNo":"20241030215465",
            "AllPayLogisticsID": "xxxxxxxxxxxxxx",
            "MerchantID": "2000132",    
            "GoodsAmount": 6800,
            "ReceiverName": "",
            "ReceiverPhone": "",
            "ReceiverCellPhone": "",
            "LogisticsType": "CVS",
            "LogisticsSubType": "FAMI"
            "IsCollection": "N",
            "Temperature": "0001",
            "Specification": "0001",
            "LogisticsStatus":"",
            "ShipmentNo":"",
            "BookingNote":"",
            "CVSPaymentNo":"",
            "CVSValidationNo":"",
            "DeliveryDate":"",
            "GoodsWeight": 2,
            "ActualWeight": 2,
            "InitShipCharge": 60,
            "ActualShipCharge": 60,
            "ExtraChargeFee": 0,
            "FeeHoldStatus": 1
            "ShipChargeDate":"",
            "CollectionAmount":0,
            "CollectionChargeFee":0,
            "CollectionAllocateAmount":0,
            "CollectionAllocateDate": "",
            "SenderStoreId": "024704",
            "SenderStoreName": "全家南港車站店",
            "ReceiverStoreId": "021556",
            "ReceiverStoreName": "全家墾丁大街店",
            "ReturnRecvStoreId": "",
            "ReturnRecvStoreName": "",
            "ReturnShipCharge": 0,
            "ReturnChargeFee": 0,
            "ReturnShipChargeDate": ""
        },
        {…},
        {…}
    ]
    
}

注意事項：當DataType=2時，回傳資料為CSV檔案

綠界Response參數說明 (CSV檔案)

訂單時間

格式為：yyyy/MM/dd HH:mm:ss

廠商訂單編號

綠界物流訂單編號

商店代號

訂單金額

收件人姓名

收件人手機 / 市話

物流廠商

請參考物流方式一覽表

服務名稱

超商門市寄/取貨
大宗寄倉超商取貨
宅配

純配送 / 貨到付款

純配送
貨到付款

溫層

常溫
冷藏
冷凍

宅配規格(長+寬+高)

物流狀態

請參考物流狀態代碼一覽表

配送編號 / 托運單號

交貨便代碼 / 店到店編號

到店日期

格式為：yyyy/MM/dd

商品重量

實際重量

初始物流運費

實際物流運費

加價費用

圈存狀態

保留中
已歸還

物流費扣款日期

格式為：yyyy/MM/dd

物流代收款項

物流代收手續費率

物流代收手續費

物流代收款項撥款金額

注意事項：

當物流代收款項撥款金額為0元時，以下2種情境不代表撥款金額為0元

若代收金額不為0且物流代收款項撥款日期無資料，表示尚未撥款
若代收金額為0元，表示本訂單為不需代收貨款

物流代收款項撥款日期

格式為：yyyy/MM/dd

備註

寄件門市代碼

寄件門市名稱

收件門市代碼

收件門市名稱

退貨門市代碼

當貨品退貨時，返回的超商門市代碼

物流子類型為C2C才會回傳

退貨門市名稱

當貨品退貨時，返回的超商門市名稱

物流子類型為C2C才會回傳

退回運費

當賣家寄出代收貨款包裹，因買家未取或拒收等因素，導致包裹退回賣家產生的運費。

退回手續費

當賣家寄出代收貨款包裹，因買家未取或拒收等因素，導致包裹退回賣家產生的手續費。

退回費扣款日期

退回運費及退回手續費的扣款日期

綠界官方網站