超商B2C/C2C / 產生物流訂單

快速導引

應用場景

消費者在特店網站選擇跨境物流運送方式並完成付款，特店依結帳資訊產生跨境物流訂單。

API介接網址

正式環境：https://logistics.ecpay.com.tw/CrossBorder/Create
測試環境：https://logistics-stage.ecpay.com.tw/CrossBorder/Create

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來驗證此次介接的時間區間。

注意事項：

驗證時間區間為 10 分鐘內有效，若超過此驗證時間則此次API request將無法建立，參考資料：http://www.epochconverter.com/。
特店需進行主機「時間校正」，避免主機產生時差，造成API request失敗。

Data String
加密資料 必填

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

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

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

Data參數說明(Json格式)

MerchantID String(10)
特店編號 必填

MerchantTradeDate String(20)
廠商訂單日期 必填

請依消費者交易的當下時間設定
(此時間不會等於綠界建立物流訂單完成的時間)
格式為：yyyy/MM/dd HH:mm:ss

MerchantTradeNo String(20)
廠商訂單編號

廠商交易編號均為唯一值，不可重複使用。
英數字大小寫混合。

LogisticsType String(20)
物流類型 必填

CB：跨境

LogisticsSubType String(20)
物流子類型 必填

UNIMARTCBCVS：統一跨境超取
UNIMARTCBHOME：統一跨境宅配

GoodsAmount Int
商品金額 必填

GoodsWeight Number
商品重量 必填

單位公斤，支援整數10位，小數2位
超取重量上限
香港 : 5KG
新加坡 : 10KG
馬來西亞 : 20KG
宅配重量上限
香港 : 20KG
新加坡 : 20KG
馬來西亞 : 20KG

GoodsEnglishName String(60)
商品英文名稱 必填

ReceiverCountry String(20)
收件人國家 必填

SG：新加坡
MY：馬來西亞
HK：香港

ReceiverName String(100)
收件人姓名 必填

注意事項：如收件人國家為香港店取時，限制為60個字。

ReceiverCellPhone String(20)
收件人手機 必填

手機號碼(全數字含國碼，不含符號空格)

注意事項：如收件人國家為香港店取時，限制為15個字。

ReceiverStoreID String(20)
收件人門市代號

店取配送：由電子地圖選來的
宅配配送：須為空白字串

注意事項：店取配送時為必填。

ReceiverZipCode String(20)
收件人宅配郵遞區號 必填

注意事項：如配送目的地為「香港」，則需填入00000

ReceiverAddress String(200)
收件人宅配地址 必填

注意事項：如收件人國家為香港店取時，限制為80個字。

ReceiverEmail String(50)
收件人Email 必填

SenderName String(100)
寄件人姓名 必填

SenderCellPhone String(20)
寄件人手機 必填

SenderAddress String(200)
寄件人地址 必填

SenderEmail String(50)
寄件人Email 必填

Remark String(200)
備註

ServerReplyURL String(200)
Server端回覆網址 必填

物流狀態都會透過此 URL 通知。

Data參數範例(Json格式)

				
					{
    "MerchantID": 2000132,
    "MerchantTradeNo": "",
    "MerchantTradeDate": "2020/05/09 10:35:04",
    "LogisticsType": "CB",
    "LogisticsSubType": "UNIMARTCBCVS",
    "GoodsWeight": 13.23,
    "GoodsAmount": 20000,
    "GoodsEnglishName": "Test goods",
    "ReceiverStoreID": "9999",
    "ReceiverCountry": "HK",
    "ReceiverName": "Receiver",
    "ReceiverCellPhone": "852912345678",
    "ReceiverZipCode": "00000",
    "ReceiverAddress":"address 23424 -fr 13-2",
    "ReceiverEmail": " xxx.xxx@xxx.com.tw ",
    "SenderName": "Sender",
    "SenderCellPhone": "886987654321",
    "SenderAddress": " address 23424 -fr 13-2, Nangang Dist., Taipei City 115, Taiwan (R.O.C.)",
    "SenderEmail": "xxx.xxx@xxx.com.tw",
    "Remark": "Test Remark",
    "ServerReplyURL": "https://logistics-stage.ecpay.com.tw/MockMerchant/NoticsTestRtn"
}

綠界回傳參數(Json格式)

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

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

MerchantID String(10)
特店編號

RpHeader Object
傳入資料

Timestamp String(10)
傳入時間

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

注意事項：

驗證時間區間為 10 分鐘內有效，若超過此驗證時間則此次API request將無法建立，參考資料：http://www.epochconverter.com/。
特店需進行主機「時間校正」，避免主機產生時差，造成API request失敗。

TransCode Int
回傳代碼

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

TransMsg String(200)
回傳訊息

回傳訊息

Data String
加密資料

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

綠界回傳參數範例

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

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

RtnCode Int
回應代碼

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

RtnMsg String(200)
回應訊息

MerchantID String(10)
特店編號

MerchantTradeNo String(20)
特店訂單編號

特店訂單編號均為唯一值，不可重複使用。
英數字大小寫混合

LogisticsID String(20)
綠界訂單編號

ShipmentNo String(20)
配送編號

LogisticsType String(20)
物流類型

LogisticsSubType String(20)
物流子類型

GoodsAmount Int
商品金額

商品遺失賠償依據，僅可使用數字，上限為台幣20,000元

GoodsWeight Number
商品重量

單位公斤，支援整數10位，小數2位
超取重量上限
香港 : 5KG
新加坡 : 10KG
馬來西亞 : 20KG
宅配重量上限
香港 : 20KG
新加坡 : 20KG
馬來西亞 : 20KG

UpdateStatusDate String(20)
物流狀態更新時間

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

ReceiverName String(100)
收件人姓名

ReceiverCellPhone String(20)
收件人手機

ReceiverCountry String(20)
收件人國家

ReceiverEmail String(50)
收件人Email

ReceiverAddress String(200)
收件地址

回傳Data參數範例

				
					{
    "RtnCode": 1,
    "RtnMsg": "成功",
    "MerchantID": 2000132,
    "MerchantTradeNo": "1234567890",
    "LogisticsID": 1234567890,
    "ShipmentNo": "GMJI7110000000001",
    "LogisticsType": "CB",
    "LogisticsSubType": "UNIMARTCBCVS",
    "GoodsAmount": 1,
    "GoodsWeight": 1.0,
    "UpdateStatusDate": "2020/05/09 10:36:04",
    "ReceiverName": "Test receiver",
    "ReceiverCellPhone": "852912345678",
    "ReceiverCountry": "HK",
    "ReceiverEmail": "xxx@xxx.com.tw",
    "ReceiverAddress": "xxxx"
}

綠界官方網站