BlackCat-Home-Delivery V2.1

黑貓宅配流程說明

將訂單資料組成Json字串Post到建立物流單

成功後，列印黑貓宅急便標籤

於出貨日將商品準備好，黑貓上門取貨

之後進入宅配流程

BlackCat-Home-Delivery流程圖

famifreezingC2Cflow

BlackCat-Home-Delivery API

網址連結

正式: https://logistic.paynow.com.tw
測試: https://testlogistic.paynow.com.tw

1. 建立物流訂單

說明

建立物流訂單

傳遞方式：Http POST method application/x-www-form-urlencoded

API URL：/api/Orderapi/Add_Order

參數	名稱	型態	長度	必須	備註
JsonOrder	物流單資料	string		Y	資料組成JSON字串以TripleDESEncoding加密後UrlEncode傳送附錄

JsonOrder Content

參數	名稱	型態	長度	必須	備註
Description	單號描述	string	50	N	商品類別(代碼) 0001：一般食品 0002：名特產/甜產印單 0003：酒/油/醋/醬 0004：穀物蔬果 0005：水產/肉品 0006：3C 0007：家電 0008：服飾配件 0009：生活用品 0010：美容彩妝 0011：保健食品 0012：醫療相關用品 0013：寵物用品飼料 0014：印刷品 0015：其他未填預設 0015
DeliverMode	取貨是否付款	string	2	Y	01:取貨付款 02:取貨不付款若是保險單須為02
Logistic_service	使用的物流服務	string	5	Y	06:黑貓宅急便 36:黑貓宅急便(PayNow)
user_account	商家主帳號	string	10	Y
apicode	商家api密碼	string	30	Y
OrderNo	商家訂單編號	string	27	Y	限英文與數字
Receiver_Name	收件人姓名	string	30	Y	中文最多10個字、英文20個字
Receiver_Phone	收件人手機	string	10	Y	Ex:0900000001
Receiver_Email	收件人EMAIL	string	120	Y
Receiver_address	收件人地址	string	120	Y	不可包含特殊字符
Sender_Name	寄件人姓名	string	30	Y	長度限制為30
Sender_Phone	寄件人手機	string	10	Y	請填空字串將會自動帶入0900000000
Sender_Email	寄件人EMAIL	string	120	Y	如不填入，請填空字串
Sender_address	寄件人地址	string	120	Y	如不填入，請填空字串(不可包含特殊符號)
Remark	備註	string	200	Y	如不填入請填空字串
PassCode	傳遞碼	string		Y	以下參數值依序組合起來成一段字串(不包含+號) : user_account + OrderNo + TotalAmount + apicode並使用sha-1雜湊函數取得組合字串的雜湊值附錄
TotalAmount	總金額	string	5	Y	正整數且金額不可大於100000
Deadline	預定出貨天數	string	int	Y	當日出貨請帶0 最多帶入6天(如帶0且過當日4點出貨日為明天)周日、連假會順延
EC	EC平台	string		N
Length	長	string	3	Y	長+寬+高不可超過150公分
Wide	寬	string	3	Y	長+寬+高不可超過150公分
High	高	string	3	Y	長+寬+高不可超過150公分
Weight	重量	string	5	Y	商品總重量(kg)不可超過20KG
Sender_Tel	寄件人市話	string	10	N	Ex:0225215088
Receiver_Tel	收件人市話	string	10	N	Ex:0225215088
ExpectDeliverTime	希望配達時間	string	1	N	1:上午13:00前 2:下午 14~18:00 4:不固定預設為4
ExpectDeliverDate	希望配達日期	string	10	N	格式為yyyy-MM-dd ex:2021-02-24 最大為成立物流單日期+6天 Ex: 2021/02/20成立訂單，希望配達日期2020-02-27則建單失敗，最大為2020-02-26 希望配達日期詳細顯示請看黑貓宅配流程，未帶入會自動設定為出貨日D+1，周日、連假會順延
DeliveryType	保溫層	string	6	Y	0001:常溫 0002:冷藏 0003:冷凍
IsInsurance	有無保險	bool		N	有保險的單填true，系統預設為false若為服務代號36的單無須帶入該值，總金額超過20000會自動保險
Receiver_Tel	收件人市話	string	7	N	若IsInsurance為true，則必填正整數金額須為20001~100000之間，DeliverMode須為02 若為服務代號36的單則無須帶入該值且總金額超過20000會自動保險(保險金額為商品金額)

Response

NewOrderReturn Content

參數	名稱	型態	長度	必須	備註
Status	狀態	string	1	Y	S:成功 F:失敗
LogisticNumber	PayNow物流單號	string	20	Y
LogisticService	物流服務名稱	string		Y	物流服務名稱Ex:黑貓宅急便
LogisticServiceID	物流服務代碼	string	2	Y	06: 黑貓宅急便 36:黑猫店到店(PayNow)
ErrorMsg	錯誤訊息	string		Y	成功則為null
paymentno	物流商貨運編號	string		Y	超商物流配送編號
ReturnMsg	回傳訊息	string		Y
orderno	商家訂單編號	string	27	Y
validationno	物流商驗證碼	string		Y

Objec Example

Request Object

{
  "DeliverMode": "01",
  "Description": "範例",
  "Logistic_service": "06",
  "OrderNo": "123456789",
  "Receiver_address": "台北市北投區承德路六段2號",
  "Receiver_Email": "12345678@gmail.com",
  "Receiver_Name": "王O明",
  "Receiver_Phone": "0912345678",
  "Remark": "備註",
  "Sender_address": "台北市中山區松江路207號9樓",
  "Sender_Email": "12345678@gmail.com",
  "Sender_Name": "李O富",
  "Sender_Phone": "0912345678",
  "Sender_Tel": "0225215088",
  "Receiver_Tel":"0225215088",
  "apicode": "12345678",
  "TotalAmount": "100",
  "user_account": "28229955",
  "DeliveryType": "0001",
  "PassCode": "2FC3805A8BEEC525F2EDF74B75E7FCE83C980856",
  "Deadline": "1"
}

Response Object

{
  "Status": "S",
  "LogisticNumber": "ABCD123456",
  "LogisticService": "黑貓宅急便",
  "LogisticServiceID":  "06",
  "paymentno": "12345678",
  "ReturnMsg": "",
  "orderno": "12345678",
  "ErrorMsg": ""
}

2. 列印黑貓宅急便標籤

說明

列印黑貓宅急便標籤

傳遞方式：Http POST method

API URL：/Member/Order/PrintBlackCatLabel

Request

參數	名稱	型態	長度	必須	備註
LogisticNumbers	Paynow物流單號組成的字串	string		Y	Paynow物流單號+底線+物流單子序號多筆之間用 , 相隔 EX:ABCD0017B21903001221_1, ABCD0017B21903001270_1

Response

回傳列印物流標籤畫面

3. 物流貨態回傳

說明

商家接收物流貨態，更新貨態時由PayNow傳送訂單貨態資料給商家

傳遞方式：Http Post method

Request

參數	名稱	型態	長度	必須
orderno	商家自訂編號	string	30	Y
OriginOrderno	商家原始自訂單號	string	27	Y
PayNowLogisticCode	物流代碼	string	4	Y
Detail_Status_Description	物流狀態描述	string		Y
paymentno	物流商託運單號	string		Y

4. 查詢物流單(PayNow物流單號)

說明

根據PayNow物流單號查詢物流單資訊

傳遞方式：Http GET method

API URL：/api/Orderapi/Get_Order_Info

Request

參數	名稱	型態	長度	必須	備註
LogisticNumber	PayNow物流單號	string	20	Y
sno	物流單序號	int		Y	固定為1

Response

參數	名稱	型態	長度	必須	備註
LogisticNumber	PayNow物流單號	string	20	Y
sno	物流單序號	string		Y
orderno	商家訂單編號	string	30	Y
Logistic_Serviece	物流服務	string	2	Y	06:黑貓宅急便 36:黑貓宅急便(PayNow)
Status	狀態	string	1	Y	0：成立中訂單 1：無效訂單
Delivery_Status	物流狀態	string	2	Y	流程狀態描述
PayNowLogisticCode	物流代碼	string	4	Y	PayNow物流代碼
Detail_Status_Description	物流代碼描述	string		Y	PayNow物流代碼詳細資訊
paymentno	物流商託運單號	string		Y
ErrorMsg	錯誤訊息	string		Y	Null則為查詢成功

Objec Example

Request Object

{
  "LogisticNumber":"MIJA0027B22112100002",
  "sno":"1",
}

Response Object

{
  "LogisticNumber":"MIJA002FR22112156425",
  "orderno":"211215145423",
  "Logistic_Serviece":"24",
  "Status":"0",
  "Delivery_Status":"等待寄件",
  "PayNowLogisticCode":"0000",
  "Detail_Status_Description":"等待寄件",
  "sno":"1",
  "ErrorMsg":null,
  "paymentno":"11000094930"
} 

5. 查詢物流單(商家訂單編號)

說明

查詢物流單(商家訂單編號)

傳遞方式：Http GET method

API URL：/api/Orderapi/Get_Order_Info_orderno

Request

參數	名稱	型態	長度	必須	備註
orderno	商家訂單編號	string	30	Y
user_account	商家主帳號	string	10	Y
sno	物流單序號	int		Y	固定為1

Response

參數	名稱	型態	長度	必須	備註
LogisticNumber	PayNow物流單號	string	20	Y
sno	物流單序號	string		Y
orderno	商家訂單編號	string	30	Y
Logistic_Serviece	物流服務	string	2	Y	06:黑貓宅急便 36:黑貓宅急便(PayNow)
Status	狀態	string	1	Y	0:成立中訂單 1:無效訂單
Delivery_Status	物流狀態	string	2	Y	流程狀態描述
PayNowLogisticCode	物流代碼	string	4	Y	PayNow物流代碼
Detail_Status_Description	物流代碼描述	string		Y	PayNow物流代碼詳細資訊
paymentno	物流商託運單號	string		Y
ErrorMsg	錯誤訊息	string		Y	Null則為查詢成功

Objec Example

Request Object

{
  "orderno":"1630206584255",
  "user_account":"28229955",
  "sno":"1",
}

Response Object

{
     "LogisticNumber":"MIJA002FR22112156425",
     "orderno":"211215145423",
     "Logistic_Serviece":"24",
     "Status":"0",
     "Delivery_Status":"等待寄件",
     "PayNowLogisticCode":"0000",
     "Detail_Status_Description":"等待寄件",
     "sno":"1",
     "ErrorMsg":null,
     "paymentno":"11000094930"
} 

6. 重新取號

說明

依商家原有訂單資料進行重新取號(PayNow物流單號、配送編號)
重新取號過的訂單若需在重取請帶入新的LogisticNumber

傳遞方式：Http POST method application/x-www-form-urlencoded

API：/api/Orderapi/ReNewOrder

Request

參數	名稱	型態	長度	必須	備註
JsonOrder	物流單資料	string		Y	以下資料組成Object後轉換JsonString以TripleDESEncoding加密後urlencode傳送附錄

Json Content

參數	名稱	型態	長度	必須	備註
user_account	商家主帳號	string	10	Y
LogisticNumber	Paynow物流單號	string	20	Y
sno	物流單序號	int		Y
OrderNo	商家訂單編號	string	27	Y	商家原始訂單編號
TotalAmount	訂單總金額	string		Y
apicode	商家api密碼	string	30	Y
PassCode	傳遞碼	string		Y	以下參數值依序組合成一段字串(不包含+號)user_account + OrderNo + TotalAmount + apicode並使用sha-1雜湊函數取得組合字串的雜湊值附錄

Response

參數	名稱	型態	長度	必須	備註
Status	狀態	string	1	Y	S:成功 F:失敗
LogisticNumber	PayNow物流單號	string	20	Y
OrderNo	商家原始訂單編號	string	27	Y
sno	物流單序號	int		Y
paynoworderno	新訂單編號	string	30	Y	重新取號後新的商家訂單編號若超過規定日期重取會取得新訂單編號，規定日期計算方式為物流單成立日加下述天數 (7-11 5天 / 全家當天 / 萊爾富 5天) 請以此訂單編號作為批次列印查詢的訂單編號
paymentno	物流商貨運編號	string		Y	重新取號後新的物流商貨運編號
ErrorMsg	錯誤訊息	string		Y	成功則為null

Objec Example

Request Object

{
  "LogisticNumber":"ABCD12345678910",
  "OrderNo": "12345678",
  "apicode": "12345678",
  "TotalAmount": "100",
  "user_account": "28229955",
  "PassCode": "2FC3805A8BEEC525F2EDF74B75E7FCE83C980856",
  "sno": "1",
}

Response Object

{
  "LogisticNumber":"ABCD0017C11902001484",
  "orderno":"test5111040",
  "paynoworderno":"test5111040",
  "sno":"1",
  "paymentno":"E2468594",
  "Status":"S",
  "ErrorMsg":null
}

7. 查詢黑貓材積

說明

查詢目前商家申請的材積

傳遞方式：Http POST method application/x-www-form-urlencoded

API：/api/BlackCat/GetBlackCatVolume

Request

參數	名稱	型態	長度	必須	備註
user_account	商家主帳號	string	10	Y
sonid	商家分店代號	string	3	Y
Logistic_Serviece	物流服務	string	2	Y	06:黑貓宅急便 36:黑貓宅急便(PayNow)

Response

參數	名稱	型態	長度	必須	備註
純字串		string			成功時回傳商家有使用的尺寸字串以,相隔 EX: S60,S90,S120失敗時回傳錯誤訊息

8. 查詢黑貓材積(api密碼)

說明

查詢目前商家申請的材積

傳遞方式：Http POST method application/x-www-form-urlencoded

API：/api/BlackCat/QueryBlackCatVolume

Request

參數	名稱	型態	長度	必須	備註
user_account	商家主帳號	string	10	Y
apicode	商家api密碼	string	30	Y	請以TripleDESEncoding加密後傳送附錄
Logistic_Serviece	物流服務	string	2	Y	06:黑貓宅急便 36:黑貓宅急便(PayNow)

Response

參數	名稱	型態	長度	必須	備註
純字串		string			成功時回傳商家有使用的尺寸字串以,相隔 EX: S60,S90,S120失敗時回傳錯誤訊息

9. 查詢黑貓設定

說明

查詢目前商家在PayNow的黑貓相關設定

傳遞方式：Http GET method application/x-www-form-urlencoded

API：/api/BlackCat/All_BlackCat_Setting

Request

參數	名稱	型態	長度	必須	備註
user_account	商家主帳號	string	10	Y
sonid	商家分店代號	string	3	Y

Response

參數	名稱	型態	備註
eshopID	設定契客代號	string	黑貓商家代號
IsOpen	PayNow服務開通狀況	string	true:開通中 false:未開通
Logistic_Serviece	物流服務	string	06:黑貓宅配 36:黑貓宅配(PayNow) 46:黑貓到店(PayNow)

10. 驗證是否有效地址

說明

驗證是否有效地址

傳遞方式：Http GET method application/x-www-form-urlencoded

API：/api/BlackCat/IsValidAddress

Request

參數	名稱	型態	長度	必須	備註
Address	地址	string		Y

Response

參數	名稱	型態	長度	必須	備註
	回傳字串	string			回傳S或F或Error:錯誤訊息

11. 驗證地址是不是特殊或偏遠地區

說明

驗證地址是不是特殊或偏遠地區(運費需加+60)

傳遞方式：Http GET method application/x-www-form-urlencoded

API：：/api/BlackCat/IsSpecialAddress

Request

參數	名稱	型態	長度	必須	備註
Address	地址	string		Y

Response

參數	名稱	型態	備註
result	請求結果	bool	true:請求成功 false:請求失敗
ErrorMsg	請求失敗錯誤訊息	string	錯誤訊息
check_result	地址檢查結果	string	true:該地址為特殊地址/偏遠地區 false:該地址非特殊地址/偏遠地區

12. 設定黑貓資料

說明

在 PAYNOW 設定黑貓資料

傳遞方式：Http GET method application/x-www-form-urlencoded

API：：/api/BlackCat/Setting_BlackCat

Request

參數	名稱	型態	長度	必須	備註
SettingJson	Json字串	string		Y	以下資料組成Object後轉換JsonString以TripleDESEncoding加密後urlencode傳送附錄

Json Content

參數	名稱	型態	長度	必須	備註
user_account	商家主帳號	string	10	Y
apicode	商家api密碼	string	30	Y
eshopID	設定契客代號	string	30	Y	黑貓商家代號
ftpusername	黑貓FTP帳號	string	30	N
ftppassword	黑貓FTP密碼	string	30	N
IsInsurance	是否有簽保險	string		Y	有簽請帶1, 沒簽帶0如eshopID為2822995505請帶1
Logistic_service	使用的物流服務	string		N	如為eshopID為2822995505此欄需填36
size	簽約包裹尺寸	string	30	Y	S60,S90,S120,S150將有簽約的以,相隔組成字串 Ex: 有簽約 S60 S90 S120即帶:S60,S90,S120 如為 eshopID 為 2822995505 此欄預設為S60,S90,S120,150
PassCode	傳遞碼	string		Y	以下參數值依序組合成一段字串(不包含+號)user_account + apicode + 黑貓契客代號並使用sha-1雜湊函數取得組合字串的雜湊值附錄

Response

參數	名稱	型態	長度	必須	備註
	回傳字串	string			成功回傳:S 失敗回傳:F,錯誤訊息

13. 更改黑貓資料

說明

變更在PAYNOW的黑貓資料

傳遞方式：Http PUT method application/x-www-form-urlencoded

API：：/api/BlackCat/Up_BlackCat_Setting

Request

參數	名稱	型態	長度	必須	備註
SettingJson	Json字串	string		Y	以下資料組成Object後轉換JsonString以TripleDESEncoding加密後urlencode傳送附錄

Json Content

參數	名稱	型態	長度	必須	備註
user_account	商家主帳號	string	10	Y
apicode	商家api密碼	string	30	Y
eshopID	設定契客代號	string	30		黑貓商家代號
ftpusername	黑貓FTP帳號	string	30	N
ftppassword	黑貓FTP密碼	string	30	N
IsInsurance	是否有簽保險	string		Y	有簽請帶1, 沒簽帶0如eshopID為2822995505請帶1
Logistic_service	使用的物流服務	string		N	如為eshopID為2822995505此欄需填36
size	簽約包裹尺寸	string	30	Y	S60,S90,S120,S150將有簽約的以,相隔組成字串 Ex: 有簽約 S60 S90 S120即帶:S60,S90,S120 如為 eshopID 為 2822995505 此欄預設為S60,S90,S120,150
PassCode	傳遞碼	string		Y	以下參數值依序組合成一段字串(不包含+號)user_account + apicode + 黑貓契客代號並使用sha-1雜湊函數取得組合字串的雜湊值附錄

Response

參數	名稱	型態	長度	必須	備註
	回傳字串	string			成功回傳:S 失敗回傳:F,錯誤訊息

BlackCat-Home-Delivery V2.1

黑貓宅配流程說明​

BlackCat-Home-Delivery API​

網址連結​

1. 建立物流訂單​

2. 列印黑貓宅急便標籤​

3. 物流貨態回傳​

4. 查詢物流單(PayNow物流單號)​

5. 查詢物流單(商家訂單編號)​

6. 重新取號​

7. 查詢黑貓材積​

8. 查詢黑貓材積(api密碼)​

9. 查詢黑貓設定​

10. 驗證是否有效地址​

11. 驗證地址是不是特殊或偏遠地區​

12. 設定黑貓資料​

13. 更改黑貓資料​

黑貓宅配流程說明

BlackCat-Home-Delivery API

網址連結

1. 建立物流訂單

2. 列印黑貓宅急便標籤

3. 物流貨態回傳

4. 查詢物流單(PayNow物流單號)

5. 查詢物流單(商家訂單編號)

6. 重新取號

7. 查詢黑貓材積

8. 查詢黑貓材積(api密碼)

9. 查詢黑貓設定

10. 驗證是否有效地址

11. 驗證地址是不是特殊或偏遠地區

12. 設定黑貓資料

13. 更改黑貓資料