From 493bf590124441dcf4a0afea747c889684aa60d4 Mon Sep 17 00:00:00 2001 From: wangfuguo Date: Mon, 1 Dec 2025 11:24:13 +0800 Subject: [PATCH] feat:增加百腾对接文档 --- order/ld/baiteng/order.md | 507 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 507 insertions(+), 0 deletions(-) create mode 100644 order/ld/baiteng/order.md diff --git a/order/ld/baiteng/order.md b/order/ld/baiteng/order.md new file mode 100644 index 0000000..bde3560 --- /dev/null +++ b/order/ld/baiteng/order.md @@ -0,0 +1,507 @@ + + +[toc] + +### 则一订单对接API + +则一提供了不同规范的API，调用则一订单服务端API前，需了解开发前须知及调用流程。本文提供了调用则一订单服务端API示例，供开发者参考。 + +#### 白名单 + +则一服务端API接口访问有IP白名单限制，需要接口调用方提供调用API的服务器IP地址。 + +#### 数据加签 + +采用md5(32位小写)算法生成签名 +appKey(则一提供) + appSecret(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(请求数据) + + +##### 接口信息 + +#### 下单 + +则一调用该接口下单给承运商 + +##### 调用方式 + +则一 ----> 百腾 + +##### 接口信息 + +###### 请求方式： + +post + +###### 请求地址： + +百腾提供 + +示例: +* 生产：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 | 是 | Y0010101001 | 承运商返回单号 | +|     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 + +###### 请求地址： + +百腾提供 + +示例: +* 生产：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 | 是 | 成功 | 说明, 取消失败时,返回具体失败原因 | +| value | Object | 是 | | 返回值 | +|     mailno | String | 是 | Y0010101001 | 承运商单号 | +|     customerNumber | String | 是 | Y0010101001 | 运输单号 | + + +##### 请求示例 + +```json +{ + "optionDate": "2025-12-01 00:00:00", + "reason": "任务取消,不发运了", + "mailno": "Z20251226001", + "customerNumber": "test20251226001", + "vin": "ZOBS89000921C" +} +``` + +##### 返回示例 + +```json +{ + "flag": true, + "code": 200, + "value": { + "mailno": "Z20251226001", + "customerNumber": "test12000302093" + }, + "message": "成功" +} +``` + +#### 路由回传 + +承运商调用该接口传输运输路由节点信息 + +##### 调用方式 + +百腾 ----> 则一 + +##### 接口信息 + +###### 请求方式： + +post + +###### 请求地址： + +* 生产：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 | 是 | | 路由信息 | +| 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": "", + "vinCode": "ZOBS89000921C", + "longitude": "113.465168", + "dimension": "31.664137" +} +``` + +##### 返回示例 + +```json +{ + "code": 200, + "message": "响应成功", + "flag": true +} +``` + + +#### 路由回传 + +承运商调用该接口传输运输路由节点信息 + +##### 调用方式 + +百腾 ----> 则一 + +##### 接口信息 + +###### 请求方式： + +post + +###### 请求地址： + +* 生产：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更新日志 + +新增 \ No newline at end of file -- libgit2 0.21.0