API订单接口开发指南 · 新零售系统帮助中心

**测试地址：**[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'); ```