**測試地址：**[https://retail-test.51zan.com](https://retail-test.51zan.com) 測試key和secret如下，與正式環境不互通 `??shop_id：184 ` `??app_key：hz5ca181f427e6c220 ` `??app_secret：1ddda1a28af0a93effefcc554f14b90d` **正式地址：**[https://retail-api.51zan.com](https://retail-api.51zan.com) **請求方式** `POST` /open/order/import 訂單導入新增 `POST` /open/order/update 訂單導入更新 **請求頭** `Content-Type: application/x-www-form-urlencoded` **請求參數** | 參數 | 是否必須 | 說明 | | --- | --- | --- | | app\_key | 是 | 系統設置 - 訂單導入 - API訂單接入 獲取 | | method | 是 | 請求方法，當前接口就是 POST | | timestamp | 是 | 當前請求時間戳(十位) | | shop\_id | 是 | 系統設置 - 店鋪管理，類型為自營的店鋪ID，如果沒有則創建 | | biz\_content | 是 | json 字符數組格式的訂單數據，最多允許包含20條，格式和說明見（4）訂單數據格式 | | sign | 是 | 簽名 | **（1）簽名方式** * 請求參數中的 sign 不參與簽名（去掉），其余每個參數的值都去除首尾空格，值為空字符串的參數不參與簽名（去掉）。 * 將參數名按字典序排序，排序后的參數轉為 query string 字符。（如 app_key=xxxx&biz_content=xxxx&……） * query string 字符再以 query string 方式連接上app_secret 得到待處理字符。（如 app_key=xxxx&biz_content=xxxx&……&app_secret=xxxx） * 待處理字符使用 sha512 算法得到哈希值，最后對哈希值做 base64 編碼得到簽名。 **（2）簽名示例代碼（PHP）**：見底部附錄 **（3）簽名有效期** 默認 10 分鐘。 **（4）訂單數據格式： 示例和說明** biz\_content的示例： ``` [{ "no": "no1234567", "amount": 70, "paid_amount": 0, "delivery_amount": 0, "status": 1, "refund_status": 0, "refund_amount": 0, "created_at": "2017-12-23 18:19:20", "paid_at": "", "consigned_at": "", "finished_at": "", "receiver_state": "浙江省", "receiver_city": "杭州市", "receiver_district": "西湖區", "receiver_town": "五馬街道", "receiver_address": "南京路100號", "receiver_name": "文章", "receiver_mobile": "13186868686", "receiver_zip": "", "buyer_username": "帥哥", "carrier_tracking_no": "", "carrier": "", "items": [{ "title": "T-shirt", "price": 30, "num": 1, "goods_no": "ox123123", "sku_no": "1", "sku_description": "" }, { "title": "NB-1", "price": 40, "num": 1, "goods_no": "0x123124", "sku_no": "2", "sku_description": "" }] }, { "no": "no1234568", "amount": 89, "paid_amount": 0, "delivery_amount": 0, "status": 1, "refund_status": 0, "refund_amount": 0, "created_at": "2017-12-24 08:09:20", "paid_at": "", "consigned_at": "", "finished_at": "", "receiver_state": "浙江省", "receiver_city": "杭州市", "receiver_district": "西湖區", "receiver_town": "五馬街道", "receiver_address": "人名路100號", "receiver_name": "張", "receiver_mobile": "13186868686", "receiver_zip": "", "buyer_username": "調皮", "carrier_tracking_no": "", "carrier": "", "items": [{ "title": "夾克-A", "price": 80, "num": 1, "goods_no": "ox123125", "sku_no": "3", "sku_description": "" }, { "title": "襪子-B", "price": 9, "num": 1, "goods_no": "0x123126", "sku_no": "4", "sku_description": "" }] }] ``` biz\_content的說明： 數組中的每個元素代表一條訂單信息，訂單中包含的 items 是這個訂單的商品信息。字段具體含義如下： | 字段 | 類型 | 說明 | 是否必須 | | --- | --- | --- | --- | | no | string | 訂單號 | 必須，不小于8位 | | amount | number | 訂單總金額（元） | 必須 | | paid\_amount | number | 用戶實付金額（元） | 必須 | | delivery\_amount | number | 買家應付郵費（元） | 必須 | | status | number | 訂單狀態 | 必須（1：未付款、2：已付款、3：部分發貨、4：已發貨、5：交付中、6：已完成、7：已關閉） | | refund\_status | number | 退款狀態 | 必須（0：未退款、1：退款申請處理中、2：歸還貨物中、3：退款被拒絕、4：退款關閉、5：退款成功） | | refund\_amount | number | 退款金額（元） | 必須 | | created\_at | string | 訂單創建時間(2019-12-12 10:11:12) | 必須 | | paid\_at | string | 訂單付款時間 | 可選 | | consigned\_at | string | 訂單發貨時間 | 可選 | | finished\_at | string | 訂單完成時間 | 可選 | | receiver\_state | string | 收貨地址(省) | 必須 | | receiver\_city | string | 收貨地址(市) | 必須 | | receiver\_district | string | 收貨地址(區) | 必須 | | receiver\_town | string | 收貨地址(街道) | 必須 | | receiver\_address | string | 收貨地址(詳細地址) | 必須 | | receiver\_name | string | 收貨人姓名 | 必須 | | receiver\_mobile | string | 聯系手機號 | 必須 | | receiver\_zip | string | 收貨人郵編 | 可選 | | buyer\_username | string | 買家賬號（用于牛客服綁定購物賬號） | 必須 | | carrier\_tracking\_no | string | 物流單號 | 可選 | | carrier | number | 物流公司 | 可選（0：未知、1：中國郵政、2：其他、3：亞風、4：長宇、5：大田、6：長發、7：跨越速運、8：中通快運、9：派易國際物流77、10：菜鳥大件-中鐵配、11：菜鳥大件-日日順配、12：遠長、13：東方匯、14：發網、15：美國速遞、16：WnDirect、17：飛遠配送:18：保宏物流、19：郵政標準快遞、20：宅急送、21：順豐速運、22：申通快遞、23：EMS、24：中通快遞、25：韻達快遞、26：百世快遞、27：圓通速遞、28：全峰快遞:29：天天快遞、30：EMS經濟快遞、31：優速快遞、32：德邦快遞、33：國通快遞、34：速爾快遞、35：聯邦快遞、36：華強物流、37：全一快遞、38：天地華宇、39：百世物流、40：龍邦速遞、41：新邦物流、42：快捷快遞、43：郵政快遞包裹、44：能達速遞、45：如風達配送、46：德邦物流:47：黑貓宅急便、48：聯昊通、49：佳吉快遞、50：飛遠(愛彼西)配送、51：信豐物流、52：E速寶、53：廣東EMS、54：百世快運、55：增益速遞） | | 以下是items商品部分 | | | | | title | string | 商品標題 | 必須 | | price | number | 商品單價 | 必須 | | num | number | 購買數量 | 必須 | | goods\_no | string | 商品編碼 | 必須 | | sku\_no | string | 商品SKU的ID | 必須 | | sku\_description | string | 商品SKU的描述 | 可選 | **返回格式** **（1）格式為Json** code返回非0情況下均表示沒成功執行，信息會在msg中返回。最終的有效訂單請通過訂單查詢接口查詢。 **（2）示例** ``` { "code": 0, "msg": "Success" } ``` **請求方式** `POST` /open/order/query/list 訂單導入查詢列表 **請求參數** | 參數 | 是否必須 | 說明 | | --- | --- | --- | | app\_key | 是 | 系統設置 - 訂單導入 - API訂單接入 獲取 | | method | 是 | 請求方法，當前接口是 POST | | timestamp | 是 | 當前請求時間戳 | | shop\_id | 是 | 系統設置 - 店鋪管理，類型為自營的店鋪ID，如果沒有則創建 | | biz\_content | 是 | json格式的查詢數據，格式和說明見（3）查詢數據格式 | | sign | 是 | 簽名 | **（1）簽名方式** 同上（訂單導入新增/更新）。 **（2）簽名有效期** 同上（訂單導入新增/更新）。 **（3）查詢數據格式-示例和說明** biz\_conent 的示例： ``` { "current_page": 1, "page_size": 10, "updated_start": "2019-01-01 10:00:00", "updated_end": "2019-01-01 11:00:00", "order_no": "12345678" } ``` biz\_content 的說明： 每個元素代表一個查詢條件，具體含義如下： | 列 | 類型 | 說明 | 是否必須 | | --- | --- | --- | --- | | current\_page | number | 當前頁碼 | 可選，默認1 | | page\_size | number | 當前頁大小 | 可選，默認10，最大不超過20 | | updated\_start | string | 訂單更新時間-起始 | 可選 | | updated\_end | string | 訂單更新時間-截止 | 可選 | | order\_no | string | 訂單號 | 可選 | **注意**：（order\_no）和 (updated\_start/updated\_end) 必須要傳一個。 **返回格式** **（1）格式為Json** code 返回非0情況下均表示沒成功執行，信息會在msg中返回；data 為返回的數據，其中 currentPage 是當前頁碼，pageSize 是每頁條數，list 是訂單列表，和導入的訂單數據含義一致。 **（2）示例** ``` { "code": 0, "msg": "Success", "data": { "currentPage": 1, "pageSize": 10, "list": [ { "no": "no1234567", "amount": 70, "paid_amount": 0, "delivery_amount": 0, "status": 1, "refund_amount": 0, "created_at": "2017-12-23 18:19:20", "paid_at": null, "consigned_at": null, "finished_at": null, "receiver_state": "浙江省", "receiver_city": "杭州市", "receiver_district": "西湖區", "receiver_town": "五馬街道", "receiver_address": "南京路100號", "receiver_name": "文章", "receiver_mobile": "13186868686", "receiver_zip": "", "buyer_username": "帥哥", "carrier_tracking_no": "", "carrier": 0, "items": [ { "title": "T-shirt2", "price": 30, "num": 1, "goods_no": "ox123123", "sku_no": "1", "sku_description": "" }, { "title": "NB-1", "price": 40, "num": 1, "goods_no": "0x123124", "sku_no": "2", "sku_description": "" } ] }, { "no": "no1234568", "amount": 89, "paid_amount": 0, "delivery_amount": 0, "status": 1, "refund_amount": 0, "created_at": "2017-12-24 08:09:20", "paid_at": null, "consigned_at": null, "finished_at": null, "receiver_state": "浙江省", "receiver_city": "杭州市", "receiver_district": "西湖區", "receiver_town": "五馬街道", "receiver_address": "人名路100號", "receiver_name": "張", "receiver_mobile": "13186868686", "receiver_zip": "", "buyer_username": "調皮", "carrier_tracking_no": "", "carrier": 0, "items": [ { "title": "夾克-A", "price": 80, "num": 1, "goods_no": "ox123125", "sku_no": "3", "sku_description": "" }, { "title": "襪子-B", "price": 9, "num": 1, "goods_no": "0x123126", "sku_no": "4", "sku_description": "" } ] } ] } } ``` **附錄** ``` /** ?*?簽名類示例 ?*/ class?SignHelper { ????public?$commonParams?=?[ ????????'app_key'???????=>?'', ????????'method'????????=>?'', ????????'timestamp'?????=>?'', ????????'shop_id'???????=>?'', ????????'biz_content'???=>?'', ????]; ????/** ?????*?獲取?query_string ?????* ?????*?@param?string?$appSecret?app_secret ?????* ?????*?@return?string ?????*/ ????public?function?getQueryString($appSecret?=?'') ????{ ????????$commonParams?=?$this->commonParams; ????????ksort($commonParams); ????????$queryString?=?http_build_query(array_merge($commonParams,?[ ????????????'app_secret'?=>?$appSecret ????????])); ????????return?urldecode($queryString); ????} ????/** ?????*?根據公共參數生成?sign ?????* ?????*?@param?string?$appSecret?app_secret ?????* ?????*?@return?string ?????*/ ????public?function?generateSign($appSecret?=?'') ????{ ????????$queryString?=?self::getQueryString($appSecret); ????????$hash?=?hash('sha512',?$queryString); ????????return?base64_encode($hash); ????} } //?用法示例(將叉叉替換為正確的值)： $s?=?new?SignHelper(); $s->commonParams?=?[ ????'app_key'???????=>?'xxxx', ????'method'????????=>?'xxxx', ????'timestamp'?????=>?'xxxx', ????'shop_id'???????=>?'xxxx', ????'biz_content'???=>?'xxxx' ]; $sign?=?$s->generateSign('xxxxxxxxxxxxxxx'); ```