[toc] ### 则一订单对接API 则一提供了不同规范的API，调用则一订单服务端API前，需了解开发前须知及调用流程。本文提供了调用则一订单服务端API示例，供开发者参考。 #### 白名单 则一服务端API接口访问有IP白名单限制，需要接口调用方提供调用API的服务器IP地址。 #### 数据加签 采用md5(32位小写)算法生成签名 appKey(则一提供) + appSecret(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(请求数据) #### 请求流程 ![请求流程](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/image/tms/1a9c6ac7-88e3-4c9c-b5f4-54de10bb39ab.png) #### 接口信息 #### 下单 则一调用该接口下单给承运商 ##### 调用方式 则一 ----> 百腾 ##### 接口信息 ###### 请求方式： * POST * Content-Type: application/json ###### 请求地址： 百腾提供 示例: * 生产：https://example.com/order/add * 测试：https://test.example.com/order/add ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数(application/json) | 名称 | 类型 | 必填 | 示例值 | 描述 | |------------------------------------------------------------|---------------|----|---------------------|------------------------------------------------| | expressCode | String | 是 | test20231226001 | 运单号 | | actualTotalCapacity        | Number | 否 | 28.5 | 体积（立方米） | | actualTotalQuantity | Integer | 否 | 100 | 包裹件数 | | actualTotalWeight | Number | 否 | 12000.5 | 重量（kg） | | cargoDesc | String | 是 | 西蒙面板 蓝色 | 货物描述 | | deliverType | String | 是 | 10 | 配送类型 | | expressDeliveryType | String | 否 | EN0215 | 快递配送类型大类，配送类型对应的枚举值编码 | | entityWarehouseCode | String | 是 | N01 | 寄件仓库编码 | | entityWarehouseName | String | 是 | 北京 | 寄件仓库名称 | | orderDate | String | 是 | 2023-04-01 00:00:00 | 下单时间 | | productList | Array[Object] | 是 | | 货物信息 | |     customerProductCode | String | 是 | 7813800017 | 产品编码 | |     customerProductDescription | String | 是 | 西蒙面板 蓝色 | 产品名称 | |     quantity | Integer | 是 | 20 | 数量 | |     sourceLineId | String | 是 | 21ae50110 | 产品明细行号 | |     vin | String | 是 | A89329003kACD | 车架号 整车业务填写 | |     brandName | String | 是 | 西蒙面板 | 品牌 整车必填 | |     modelName | String | 是 | 西蒙面板 | 型号 整车必填 | |     color | String | 是 | 蓝色 | 颜色 | | productType | Integer | 否 | 160 | 快件产品类别 (可根据需要定制扩展) 1、生鲜，食品 | | remark | String | 否 | 需要雨布和尾板 | 备注 | | returnRoute | Integer | 否 | 1 | 是否需要返回路由 1、是 2,否 | | returnOrder | Integer | 否 | 1 | 是否需要签回单，1：纸质返单，2：电子返单，3：纸质+电子，0：不需要 | | returnTrackingRemark | String | 否 | 签名 | 签回单要求 | | returnTrackingRemarkEnum | String | 否 | | 签回单要求枚举编码 | | vin | String | 否 | | 车架号(整车业务必填) | | deliveryTruckNo | String | 否 | | 派车单号(整车业务必填) | | packageService | String | 否 | | 包裹编号丹鸟一单多件需要分多次下单，需要传包裹号 | | platformOrderCode | String | 否 | | 平台订单编码 电商用 | | platformShipmentNo | String | 否 | | 平台发货单号 电商用 | | templateUrl | String | 否 | http://sss.com/xxx | 标准模板URL 电商用 | | shopNick | String | 否 | | 店铺名称 电商用 | | shopCode | String | 否 | | 店铺编码 快手必填 | | senderInfo | Object | 是 | | 发件人信息 | |     countryName | String | 是 | 中国 | 国家名称 | |     provinceName | String | 是 | 上海 | 省份名 | |     cityName | String | 是 | 上海市 | 城市名 | |     countyName | String | 是 | 青浦区 | 区域名称 | |     detailAddress | String | 是 | 空港物流园八街七号 | 详细地址 | |     company | String | 否 | 则一 | 公司 | |     name | String | 是 | 张三 | 姓名 | |     mobile | String | 是 | 18801000001 | 手机号 | |     tel | String | 否 | 0219909292 | 电话号码 | | receiverInfo | Object | 是 | | 收件人信息 | |     countryName | String | 是 | 中国 | 国家名称 | |     provinceName | String | 是 | 北京 | 省份名 | |     cityName | String | 是 | 北京市 | 城市名 | |     countyName | String | 是 | 朝阳区 | 区域名称 | |     detailAddress | String | 是 | 空港物流园八街七号 | 详细地址 | |     company | String | 否 | | 公司 | |     name | String | 是 | 张三 | 姓名 | |     mobile | String | 是 | 18801000001 | 手机号 | |     tel | String | 否 | 0219909292 | 电话号码 | | extendPropertites | Object | 否 | | 附加属性 | |     addedService | Array[object] | 否 | | 增值服务 | |        name | String | 否 | 20 | 增值服务名称 | |        value | String | 否 | 20 | 增值服务代码 | |        value1 | String | 否 | 20 | 增值服务代码 | |        value2 | String | 否 | 20 | 增值服务代码 | |        value3 | String | 否 | | 增值服务代码 | |        value4 | String | 否 | | 增值服务代码 | |        value5 | String | 否 | | 增值服务代码 | |     identification | String | 否 | | 寄件人证件号码 | |     identificationType | String | 否 | | 寄件人证件类型，1：居民身份证 ；2：港澳居民来往内地 | |     regionAnalysis | String | 否 | | 添加此字段表示开通行政区域解析功能:0：关闭 1：开通行政区域解析功能 4：开通行政解析功能 | |     singBackInfo | String | 否 | | 把枪信息 | |        remRfCode | String | 否 | | 把枪备注提示code | |        remRfMsg | String | 否 | | 把枪备注提示信息 | |     isvClientCode | String | 否 | | 独立顾客编码 | ###### 返回值 | 名称 | 类型 | 必填 | 示例值 | 描述 | |---------------------------------------------------|----------------|----------------------------|-------------|------------------------| | flag | Boolean | 是      | true | 成功标志 | | code | Integer | 是 | 200 | 返回码 200成功，3000承运商异常 | | message | String | 是 | 成功 | 说明 | | value | Object | 是 | | 返回值 | |     mailno | String | 是 | Y0010101001 | 承运商单号 | |     returnMailno | String | 否 | | 承运商返回单号 | |     orderDetails | Array [object] | 是 | | 货物描述 | |       forwardMailNo | String | 是 | Y0010101001 | 承运商单号 | |       isReturnFlag | String | 是 | 0 | 是否为返单数据 0正常运单数据，1返回单数据 | ##### 请求示例 ```json { "expressCode": "hxtest20231226001", "actualTotalCapacity": 10, "actualTotalQuantity": 1, "actualTotalWeight": 1, "cargoDesc": "西蒙面板 蓝色", "customerNumber": "hxtest20231226001", "deliverType": 10, "expressDeliveryType":"EN0215", "entityWarehouseCode": "N01", "entityWarehouseName": "北京", "orderDate": "2023-04-01 00:00:00", "productList": [ { "customerProductCode": "7813800017", "customerProductDescription": "西蒙面板 蓝色", "quantity": 10, "sourceLineId": "b629f33b-b205-458e-a388-12712b488445" } ], "productType": 160, "remark": null, "returnMailno": null, "returnRoute": 1, "returnOrder": 1, "returnTrackingRemark": "签名", "returnTrackingRemarkEnum": "", "subMailno": null, "verificationCode": "SHOW_ED", "senderInfo": { "countryName": "中国", "cityName": "北京市", "company": null, "countyName": "顺义区", "detailAddress": "空港物流园八街七号（中心仓）", "mobile": "13910568648", "name": "刘浩", "provinceName": "北京", "tel": "13910568648" }, "extendPropertites": { "addedService": [ { "name": "20", "value": "20", "value1": "20", "value2": "20" } ], "identification": null, "identificationType": null, "regionAnalysis": null, "singBackInfo": { "remRfCode": null, "remRfMsg": null }, "valinsPay": null }, "receiverInfo": { "countryName": "中国", "cityName": "北京市", "company": null, "countyName": "东城区", "detailAddress": "北京北京市东城区123", "mobile": "07115112227", "name": "杨", "provinceName": "北京", "tel": "07115112227" } } ``` ##### 返回示例 ```json { "flag": true, "code": 200, "value": { "mailno": "ZY1160307865367", "returnMailno": "ZY1200030442093", "orderDetails": [ { "forwardMailNo": "ZY1160307865367", "isReturnFlag": "0" } ] }, "message": "成功" } ``` #### 取消订单 则一调用该接口取消已下发给承运商的订单 ##### 调用方式 则一 ----> 百腾 ##### 接口信息 ###### 请求方式： post * Content-Type: application/json ###### 请求地址： 百腾提供 示例: * 生产：https://example.com/order/cancel * 测试：https://test.example.com/order/cancel ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数(application/json) | 名称 | 类型 | 必填 | 示例值 | 描述 | |-------------------|----------------|----------------------------|----------------------|-------------| | mailno | String | 是      | Z20251226001 | 承运商单号 | | customerNumber | String | 是 | test20251226001 | 运输单号 | | reason | String | 是 | 任务取消,不发运了 | 取消原因 | | vin | String | 否 | ZOBS89000921C | 车架号(整车业务必填) | | optionDate | String | 是 | 2025-12-01 00:00:00 | 操作时间 | ###### 返回值 | 名称 | 类型 | 必填 | 示例值 | 描述 | |-------------------------------------|----------------|----------------------------|---------------|------------------| | flag | Boolean | 是      | true | 成功标志 | | code | Integer | 是 | 200 | 返回码 200成功，3000承运商异常 | | message | String | 是 | 成功 | 说明, 取消失败时,返回具体失败原因 | ##### 请求示例 ```json { "optionDate": "2025-12-01 00:00:00", "reason": "任务取消,不发运了", "mailno": "Z20251226001", "customerNumber": "test20251226001", "vin": "ZOBS89000921C" } ``` ##### 返回示例 ```json { "flag": true, "code": 200, "message": "成功" } ``` #### 路由回传 承运商调用该接口传输运输路由节点信息, 其中必传的节点: 80-启运，81-在途，001: 签收 / 002: 签收异常 ##### 调用方式 百腾 ----> 则一 ##### 接口信息 ###### 请求方式： post * Content-Type: application/json ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/baiTengOrder/routePush * 测试：https://test.shjiuze.cn/oms-service-api/baiTengOrder/routePush ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数(application/json) | 名称 | 类型 | 必填 | 示例值 | 描述 | |---------------------| ------ |---------------------------|--------------------------------|----------------| | mailno | String | 是 | Z20251226001 | 承运商运单号 | | scanTypeCode | String | 是     | 80 | 路由类型编码, 见附录1 | | operator | String | 是 | 张三 | 操作人 | | time | String | 是 | 2025-12-01 00:00:00 | 时间 | | plannedDeliveryDate | String | 是 | 2025-12-02 00:00:00 | 预计到货时间(整车运输必填) | | transferAddress | String | 是 | 上海市青浦区纪鹤公路1988号 | 路由地点 | | memo | String | 是 | 快件在【XXX营业点】已装车,准备发往 【XXX集散中心】 | 路由信息 | | vinCode | String | 否 | ZOBS89000921C | VIN码 | | longitude | String | 否 | 113.465168 | 经度 | | dimension | String | 否 | 31.664137 | 纬度 | ###### 返回值 | 名称 | 类型 | 必填 | 示例值 | 描述 | |-------------------------------------|----------------|----------------------------|---------------|---------------------| | flag | Boolean | 是      | true | 成功标志 | | code | Integer | 是 | 200 | 返回码 200成功，3000承运商异常 | | message | String | 是 | 成功 | 说明 | ##### 请求示例 ```json { "mailno": "Z20251226001", "scanTypeCode": "80", "operator": "张三", "time": "2025-12-01 00:00:00", "plannedDeliveryDate": "2025-12-02 00:00:00", "transferAddress": "上海市青浦区纪鹤公路1988号", "memo": "快件在【XXX营业点】已装车,准备发往 【XXX集散中心】", "vinCode": "ZOBS89000921C", "longitude": "113.465168", "dimension": "31.664137" } ``` ##### 返回示例 ```json { "code": 200, "message": "响应成功", "flag": true } ``` #### 签收图片回传 承运商调用该接口回传签收图片 ##### 调用方式 百腾 ----> 则一 ##### 接口信息 ###### 请求方式： post * Content-Type: application/json ###### 请求地址： * 生产：https://gw.shjiuze.cn/oms-service-api/baiTengOrder/sign * 测试：https://test.shjiuze.cn/oms-service-api/baiTengOrder/sign ###### Headers参数 | 名称 | 类型 | 必填 | 示例值 | 描述 | | ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ | | appKey | String | 是 | 0867ef5f23ef6483749e19e1692b | 则一提供 | | timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 | | nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 | | sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 | ###### Body参数(application/json) | 名称 | 类型 | 必填 | 示例值 | 描述 | |---------------------------------|----------------|---------------------------|--------------------------------|--------------------------------------------------| | mailno | String | 是 | Z20251226001 | 承运商运单号 | | imageType | String | 是     | imageUrl | 图片内容格式类型, imageBase64-图片的base字符串，imageUrl-图片的url | | imageInfos | Array [Object] | 是 | | 图片信息 | |     imageName | String | 是 | 签收照片 | 图片名称 | |     extendName | String | 是 | jpg | 图片扩展名 | |     imageContent | String | 是 | https://shjiuze.cn/xxx/xxx.jpg | 图片内容 | |     imageSize | String | 否 | | 图片大小 | ###### 返回值 | 名称 | 类型 | 必填 | 示例值 | 描述 | |-------------------------------------|----------------|----------------------------|---------------|---------------------| | flag | Boolean | 是      | true | 成功标志 | | code | Integer | 是 | 200 | 返回码 200成功，3000承运商异常 | | message | String | 是 | 成功 | 说明 | ##### 请求示例 ```json { "mailno": "Z20251226001", "imageType": "imageUrl", "imageInfos": [ { "imageName": "回单照片", "extendName": "jpg", "imageContent": "https://shjiuze.cn/xxx/xxx.jpg" } ] } ``` ##### 返回示例 ```json { "code": 200, "message": "响应成功", "flag": true } ``` ### 附录一 ##### 路由节点类型 001: 签收 100: 到达 80：汽运-启运 81：汽运-在途 82：汽运-派送 83：空运-航班信息 84：空运-起飞时间 85：空运-降落时间 86：空运-提货时间 87：空运-派送时间 101：入站 102：分配派送员 103：妥投 104：滞留 105：拒收 89: 到达目的城市 90: 空运-入目的库 91: 空运-出目的库 92：汽运-中转库入库 93：汽运-中转库出库 94：汽运-入目的库 95：汽运-出目的库 96：汽运-装车 97：汽运-发运 98：汽运-中转装车 99：汽运-中转发运 002: 签收异常 ### Java-sdk下载 [zy-java-sdk](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar) ### 2025-12-01更新日志 新增