物流整合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/Helper/QueryCheckAccounts
  • 正式環境：https://logistics.ecpay.com.tw/Helper/QueryCheckAccounts

HTTPS傳輸協定

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

特店Request參數說明

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

  • 由綠界科技提供，此參數為專案合作的平台商使用，一般廠商介接請放空值。
  • 若為專案合作的平台商使用時，請帶賣家所綁定的MerchantID。

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：中華郵政

❗ 注意事項：

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

CheckMacValue String
檢查碼 必填

請參考附錄檢查碼機制

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

綠界Response參數說明 (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
初始物流運費

ActualShipCharge Int
實際物流運費

ExtraChargeFee Int
加價費用

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

  • 1：保留中
  • 2：已歸還

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

格式為：yyyy/MM/dd

CollectionAmount Int
物流代收款項

CollectionChargeFee Int
物流代收金額手續費

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

❗ 注意事項：

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

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

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

格式為：yyyy/MM/dd

SenderStoreId String(10)
寄件門市代碼

SenderStoreName String(40)
寄件門市名稱 

ReceiverStoreId String(10)
收件門市代碼 

ReceiverStoreName String(40)
收件門市名稱 

ReturnRecvStoreId String(10)
退貨門市代碼

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

ReturnRecvStoreName String(40)
退貨門市名稱 

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

ReturnShipCharge Int
退回運費

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

ReturnChargeFee Int
退回手續費

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

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

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

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

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

訂單時間

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

廠商訂單編號

綠界物流訂單編號

商店代號

訂單金額

收件人姓名

收件人手機 / 市話

物流廠商

請參考物流方式一覽表

服務名稱

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

純配送 / 貨到付款

  • 純配送
  • 貨到付款

溫層

  • 常溫
  • 冷藏
  • 冷凍

宅配規格(長+寬+高)

物流狀態

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

配送編號 / 托運單號

交貨便代碼 / 店到店編號

到店日期

格式為：yyyy/MM/dd

商品重量

實際重量

初始物流運費

實際物流運費

加價費用

圈存狀態

  • 保留中
  • 已歸還

物流費扣款日期

格式為：yyyy/MM/dd

物流代收款項

物流代收手續費率

物流代收手續費

物流代收款項撥款金額

❗ 注意事項：

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

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

物流代收款項撥款日期

格式為：yyyy/MM/dd

備註

寄件門市代碼

寄件門市名稱

收件門市代碼

收件門市名稱

退貨門市代碼

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

退貨門市名稱

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

 

退回運費

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

 

退回手續費

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

 

退回費扣款日期

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

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

綠界官方網站