# 3TMS/CTMS第三方接口文档
------
- [接口简介(**请仔细阅读!**)](#接口简介)
- [接口说明](#接口说明)
- **[常见问题指南(有问题先看这!)](PROBLEMS.md)**
- [获取登陆凭证接口](#获取登陆凭证接口)
- [更新登陆凭证接口](#更新登陆凭证接口)
- [创建订单接口](#创建订单接口)
- [查询订单接口](#查询订单接口)
- [查询订单接口V2](#查询订单接口v2)
- [批量查询订单接口](#批量查询订单接口)
- [撤销订单接口](#撤销订单接口)
- [创建车次接口](#创建车次接口)
- [更新批次接口](#更新批次接口)
- [创建数据看板接口](#创建数据看板接口)
- [创建数据看板库存接口](#创建数据看板库存接口)
- [追加订单货物接口](#追加订单货物接口)
- [修改订单货物接口](#修改订单货物接口)
- [删除订单货物接口](#删除订单货物接口)
- [订单订阅接口](#订单订阅接口)
- [取消订单订阅接口](#取消订单订阅接口)
- [车次订阅接口](#车次订阅接口)
- [取消车次订阅接口](#取消车次订阅接口)
- [获取组织机构列表接口](#获取组织机构列表接口)
- [添加客户接口](#添加客户接口)
- [创建受理单接口](#创建受理单接口)
- [更新受理单接口](#更新受理单接口)
- [批量查询受理单接口](#批量查询受理单接口)
- [撤销受理单接口](#撤销受理单接口)
- [批量解绑受理单设备](#批量解绑受理单设备)
- [部分参数说明](#部分参数说明)
- [错误码说明](#错误码说明)
## 接口简介
本文档为3TMS/CTMS第三方开放接口文档，操作流程为：
1. 注册并开通TMS账号（正式环境账号联系实施，应该已经开通过了）；
2. 获取接口访问令牌（token令牌只需获取一次即可，**有效期为一年！**）；
3. 调用TMS提供的接口（需要先获取令牌（access_token））；
4. 所有接口需要使用主账号调用，类似创建订单之类的接口需要使用主账号调用以后系统中才能看到！
**请使用主账号获取对应的token再调用其他接口!!!**
- **什么是主账号**：即贵公司在我们系统中创建的第一个账号，其后所有的贵公司系统中的账号都是子账号。如果不知道自己是否使用的主账号或者主账号具体是哪个请联系相关负责人。
- **接口统一URL地址**：测试环境=http://api.test.56ctms.com ，正式环境=http://api.56ctms.com
- **测试环境系统地址**：3TMS=http://go3tms.test.56ctms.com ，cTMS=http://test.56ctms.com
- **测试环境账号**：账号=19012345678 ，密码=123456 账号并不互通，此账号对应的是测试环境的域名，正式环境无法使用！
- **获取接口访问令牌**： /login.html?redirectUri=你们的回调地址（获取令牌（access_token）） (PS：输入申请到的CTMS账号密码)
此外，也可以通过调用[获取登陆凭证接口](#获取登陆凭证接口)生成令牌
- **调用接口方式**：url + ?access_token=生成的token，参数传递使用JSON格式，例：http://api.test.56ctms.com/customer_order/create_customer_order?access_token=fe12047e-52b1-418c-848c-d08a885095a5
**请勿将请求参数拼接在URL中传递！**
- **调试地址**： /swagger-ui.html
## 接口说明
所有接口支持RESTful的方式访问，返回结果首先判断http状态码，有如下几种情况：
1. 404表示接口不存在，请检查调用的接口地址，协议的格式是否正确
2. 401表示授权失败，需要重新登陆获取access_token
3. 200，201，20*表示调用接口成功，返回body中调用结果，是http JSON格式的，包含以下字段
4. 接口中所有时间均使用时间戳，单位为秒
- **code**：状态码，取值有 200，非200；200 表示接口调用成功， 非200 表示接口调用失败
- **message**：错误信息，当接口调用失败（状态码为 非200）时，返回的错误信息
- **data**：返回数据，接口调用成功（状态码为 200）之后返回的数据
## 获取登陆凭证接口
**简要描述：** 获取登陆凭证
**请求 URL：** `/user/generate_access_token/v2`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `userName` | 是 | `String` | `账号` |
| `password` | 是 | `String` | `密码` |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null,
"data": {
"accessToken": "9d0dfe02-2349-421c-90ec-4b9ea174701b",
"refreshToken": "9f8326bc-c29f-4a28-a512-26caa1a9850a"
}
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "账号或密码不正确"
}
```
## 更新登陆凭证接口
**简要描述：** 更新登陆凭证
**请求 URL：** `/user/refresh_access_token/v2`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `userName` | 是 | `String` | `账号` |
| `refreshToken` | 是 | `String` | `刷新凭证` |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null,
"data": {
"accessToken": "9d0dfe02-2349-421c-90ec-4b9ea174701b",
"refreshToken": "9f8326bc-c29f-4a28-a512-26caa1a9850a"
}
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "账号或刷新凭证不正确"
}
```
## 创建订单接口
**简要描述：** 开单
**请求 URL：** `/order/create_order`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orderList` | 是 | Array[[OrderEntity](#运单参数说明)] | 运单列表 |
**返回示例**
- 调用成功示例
调用成功但是系统中查看不到时请先阅读常见问题
```java
{
"code": 200,
"data": ["1712051703640558"],
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "订单创建失败"
}
```
## 查询订单接口
**简要描述：** 请使用查询订单v2接口
**请求 URL：** `/order/find_order`
**请求方式：** get
**需要认证：** 是
**调用频率限制：** 一小时内最多调用一万次，超过会提示操作频繁
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orderNumber` | 否 | `String` | 订单号，多个订单用','隔开 |
| `phoneNumber` | 否 | `String` | 发货人手机号 |
| `customerNumber` | 否 | `String` | 客户自定义单号 |
||||不传任何参数则查询所有|
## 查询订单接口v2
**简要描述：** 查询订单v2，包含详细的货物信息
**请求 URL：** `/order/find_order/v2`
**请求方式：** POST
**需要认证：** 是
**调用频率限制：** 一小时内最多调用一万次，超过会提示操作频繁
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orderNumber` | 否 | `String` | 订单号，多个订单用','隔开 |
| `phoneNumber` | 否 | `String` | 发货人手机号 |
| `customerNumber` | 否 | `String` | 客户自定义单号 |
||||不传任何参数则查询所有|
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null,
"data": [
{
"number": "1707171455038482",// 订单号
"wmsNumber": null,// wms订单号
"wmsLocation": null, // 集货号
"deliveryTime": 1500274800,// 提货时间
"customerOrderNumber": "", // 客户单号
"consigner": { // 发货人
"name": "张三",//姓名
"phone": "13311111111",//电话
"address": {
"province": null,//省
"city": null,//市
"district": null,//地区
"name": "计量大厦",//详细地址
"address": "计量大厦",//详细地址
"lng": 120.12592,//纬度
"lat": 30.277378//经度
}
},
"consignees": [//收货人
{
"name": "李四",//姓名
"phone": "13311111111",//电话
"address": {
"province": null,//省
"city": null,//市
"district": null,//地区
"name": "计量大厦",//详细地址
"address": "计量大厦",//详细地址
"lng": 120.12592,//纬度
"lat": 30.277378//经度
}
}
],
"cargo": {//货物
"name": "书本",//货物名称
"quantity": 3,//数量
"weight": 55,//重量（KG）
"volume": 6,//体积(L)
"value": 56,//货值（元）
},
"freightIn": {//上游运费
"amount": 22
},
"freightOut": {//下游运费
"amount": 11
},
"paymentCollect": 33,//代收货款
"needReceipt": 1,//是否需要回单
"receiptCount": 1,//回单数量
"note": "",//备注
"state": 2000,//状态
"publishTime": 1500274522,//发布时间
"receiveTime": 1500274522,//接单时间
"shipmentTime": null,//装货时间
"signedTime": null,//签收时间
"receiptStatus": null,//接单状态
"created": 1500274505,//订单创建时间
}
]
}
```
- 调用失败示例
```java
{
"status": 500,
"message": ""
}
```
## 批量查询订单接口
**简要描述：** 批量查询订单，不包含详细的货物信息
**请求 URL：** `/order/query_orders`
**请求方式：** POST, GET
**需要认证：** 是
**调用频率限制：** 一小时内最多调用一万次，超过会提示操作频繁
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `page` | 是 | `int` | 页码，1开始 |
| `size` | 是 | `int` | 单页最大订单数 |
| `state` | 否 | `int` | 订单状态，0已撤销，1已下单，2已接单，3已装货，4已签收，1000待处理，无法查看全部状态，不传则默认0已撤销|
| `timeType` | 否 | `string` | 查询时间类型，created录入时间，deliveryed提货时间，appointArrived预约提货时间，signed签收时间 |
| `startDate` | 否 | `string` | 起始时间，格式"yyyy-MM-dd HH:mm:ss" |
| `endDate` | 否 | `string` | 结束时间，格式"yyyy-MM-dd HH:mm:ss" |
| `customerOrderNumber` | 否 | `string` | 客户单号 |
| `packNumber` | 否 | `string` | 车次号 |
| `consignerName` | 否 | `string` | 发货人姓名，模糊搜索 |
| `consignerPhone` | 否 | `string` | 发货人电话，模糊搜索 |
| `consigneeName` | 否 | `string` | 收货人姓名，模糊搜索 |
| `consigneePhone` | 否 | `string` | 收货人电话，模糊搜索 |
| `driverName` | 否 | `string` | 司机姓名，模糊搜索 |
| `driverPhone` | 否 | `string` | 司机电话，模糊搜索 |
| `carNumber` | 否 | `string` | 司机车牌号码，模糊搜索 |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null,
"data": {
"page": 1,
"size": 50,
"total": 100,
"elements": [
{
"id": "5c4ad2619c023a001044079a", //订单id
"uid": "5bc725b6e4b07d20a861600f", //主账号uid
"number": "1901251709800228", //运单号
"wmsNumber": null, //wmsNumber，即创建订单时的orderNumber
"wmsLocation": null, //集货位
"operator": "5bc725b6e4b07d20a861600f", //操作人uid
"createUserId": "15161181167", //创建人手机号
"createUsername": "gmw", //创建人姓名
"deliveryTime": 1548669600, //提货时间，秒为单位的时间戳
"deliveryType": null, //提送类型 1, "自提" 2, "送货"
"appointArriveTime": 1548980160, //预约送达时间，秒为单位的时间戳
"customerOrderNumber": "JSOUT1234567", //客户单号
"startAddress": "杭州", //起始地址
"endAddress": "千岛湖", //目的地址
"consigner": { //发货方信息
"name": "发货方", //发货人姓名
"phone": "15161151543", //发货人手机
"address": { //发货人地址相关信息
"province": null, //省
"cityCode": null, //城市代码
"city": null, //城市
"district": null, //区
"name": "浙江省温州市鹿城区浙江温州化工总厂",
"address": "浙江省温州市鹿城区浙江温州化工总厂", //地址
"lng": 120.579412, //经度
"lat": 28.024421 //纬度
}
},
"consignees": [ //收货方信息
{
"name": "收货方",
"phone": "15161128126",
"address": {
"province": null,
"cityCode": null,
"city": null,
"district": null,
"name": "浙江省杭州市淳安县绿城千岛湖喜来登度假酒店",
"address": "浙江省杭州市淳安县绿城千岛湖喜来登度假酒店",
"lng": 119.039414,
"lat": 29.608042
}
}
],
"cargo": {
"id": null, //货物id
"uid": null, //创建人id
"name": "货物1", //货物名字，取第一个货物的名字
"quantity": 3, //货物总数量
"weight": 5, //货物总重量
"volume": 7, //货物总体积
"productModel": "货物1备注", //货物备注
"note1": "货物1备注1", //货物自定义备注1
"note2": "货物1备注2", //货物自定义备注2
"note3": "货物1备注3", //货物自定义备注3
"note4": "", //货物自定义备注4
"note5": "", //货物自定义备注5
"note6": "", //货物自定义备注6
"value": null, //货值
"consignerPhone": null, //发货人手机号
"consigneePhones": null, //收货人手机号
"created": null, //创建货物时间
"updated": null //更新货物数据时间
},
"totalCargoes": 2, //货物总数量
"settlementParty": 1, //结算方
"freightIn": { //上游运费
"payType": 1, //上游费用支付方式， 1现付，2到付，3回付，4周结，5月结
"amount": 11 //上游费用
},
"freightOut": { //司机运费
"payType": 5, //上游费用支付方式， 1现付，2到付，3回付，4周结，5月结
"amount": 12 //司机费用
},
"totalFreightIn": 11, //总上游费用
"freightReceived": null, //已收费用
"freightUnreceived": 11, //未收费用
"freightCollect": null, //代收运费
"freightCollectReceived": null, //已收代收运费
"freightCollectUnReceived": 0, //未收代收运费
"paymentCollect": null, //代收货款
"paymentCollectReceived": null, //已收代收货款
"paymentCollectUnReceived": 0, //未收代收货款
"needReceipt": 1, //是否需要回单
"receiptCount": 1, //回单数量
"note": "运单备注", //运单备注
"extraFields": {
"uppay1": "", // 上游自定义运费1
"uppay2": "", // 上游自定义运费2
"uppay3": "", // 上游自定义运费3
"uppay4": "", // 上游自定义运费4
"uppay5": "", // 上游自定义运费5
"uppay6": "", // 上游自定义运费6
"pay1": "", // 司机自定义运费1
"pay2": "", // 司机自定义运费2
"pay3": "", // 司机自定义运费3
"pay4": "", // 司机自定义运费4
"pay5": "", // 司机自定义运费5
"pay6": "", // 司机自定义运费6
"note1": "", // 自定义备注1
"note2": "", // 自定义备注2
"note3": "", // 自定义备注3
"note4": "", // 自定义备注4
"note5": "", // 自定义备注5
"note6": "", // 自定义备注6
"note7": "", // 自定义备注7
"note8": "", // 自定义备注8
"note9": "", // 自定义备注9
"note10": "", // 自定义备注10
"note11": "", // 自定义备注11
"note12": "" // 自定义备注12
},
"option1": null, //自定义选项1
"option2": null, //自定义选项2
"option3": null, //自定义选项3
"organizationPath": "0", //所属组织机构的path字段(不是名字)，具体请参考常见问题指南
"dispatchInfo": { //调度信息
"driverPhone": null, //司机电话
"driverUids": [], //司机列表
"gids": [], //车队列表
"carMode": null, //车型
"orderCount": 1, //生成订单数量
"shouldNotifyDriver": false, //是否给司机发动提醒
"needDriverAgree": false, //是否需要司机同意，默认否(只有一个订单时有效)
"driverTags": null, //司机标签
"vehicleTagIds": null //车辆标签
},
"batchId": null, //批量导入的批次id
"createUid": "5bc725b6e4b07d20a861600f", //开单人
"source": 1, //订单来源，1手工录入，2标准导入，4接口导入
"state": 2000, //状态 0:"已撤销" 1000:"待处理" 2000:"已发布"
"parentOrderId": null, //父订单id
"splitOrderId": null, //拆分源订单
"planNumber": null, //任务计划的编号
"omsNumber": null, //受理单号
"packNumber": "P1901255BCE400F0001", //车次号
"waybillState": 2, //运单状态，state为2000时才会有值，1已下单，2已接单，3已装货，4已签收
"dispatchDriver": { //司机信息
"uid": "5c4a7f86e4b0f2d798da543e", //司机账号的id
"username": "司机姓名", //名字
"phoneNumber": "13872897189", //电话
"carNumber": "浙A92874", //车牌号
"carMode": 1, //车型
"carDetailMode": 0, //详细车型
"passType": 0, //通行证类型 0:未指定 1:邮政通 2:绿通 3:全市通 4:三环通 5:江南通 6:江北通
"passTypeValue": "" //通行证
},
"evaluate": null, //评价
"miles": 342, //预估里程
"openTime": null, //开单时间
"publishTime": 1548407457, //发布时间
"receiveTime": 1548407457, //接收时间
"shipmentTime": null, //装货时间
"signedTime": null, //签收时间
"receiptCallbackTime": null, //回单回收时间
"receiptSendOutTime": null, //回单发放时间
"evaluateTime": null, //评价时间
"receiptStatus": null, //回单状态 回单已回收,回单已发放
"receiptUploaded": null, //回单是否已上传
"settlementStatus": null, //运费状态
"freightCollectStatus": null, //代收运费状态 0:未收取 1:已收取 2:已核销 3:部分收取 99:所有
"collectionAmountStatus": null, //代收货款状态 0:未收取 1:已收取 2:已核销 3:部分收取 99:所有
"orderSendType": 1, //订单指派方式 1：指派 2：抢单P
"orderPrintStatus": null, //订单打印状态 1：已打印
"tipsPrintStatus": null, //订单标签打印状态 1：已打印
"segmentNumber": null, //分段number
"segmentType": null, //分段类型 0:提货,5:提货到外转方,1:中转,2:直送,3:外转直送,4:外转中继
"segmentReceiveOrganizeidPath": null, //分段收货方组织机构
"freezeDeliveryTime": null, //继承提货时间
"freezeAppointArriveTime": null, //继承预约到达时间
"freezeStartAddress": null, //继承起始地
"freezeEndAddress": null, //继承目的地
"freezePaymentCollect": null, //继承代收货款
"abnormal": null, //异常标记
"abnormal_dispose_status": null, //异常处理标记
"deliveryAddress": null, //装货地址
"signAddress": null, //签收地址
"onlinePayState": null, //在线支付状态 1 支付中，2支付成功
"onlinePayment": null, //在线支付金额
"transactionId": null, //交易流水号
"isDelete": null, //是否删除 1为删除
"created": 1548407393, //订单创建时间
"updated": 1548407458, //订单更新时间
"startAddressLng": null, //起点经度
"startAddressLat": null, //起点纬度
"endAddressLng": null, //终点经度
"endAddressLat": null, //终点纬度
"financeCollectFixedTime": null, //代收货款核销时间
"freightCollectFixedTime": null, //代收运费核销时间
"apportionFee": null, //车次分摊费用
"checkPickUpAlarm": null, //提货超时是否检查：1：检查过
"checkDeliverAlarm": null, //送货超时是否检查：1：检查过
"onlinePay": false //是否在线支付
}
]
}
}
```
- 调用失败示例
```java
{
"status": 500,
"message": ""
}
```
## 撤销订单接口
**简要描述：** 批量撤销订单，撤销的订单会进入回收站中。只有状态为：待处理，已下单，已接单的运单可以撤销
**请求 URL：** `/order/cancel_orders/v2`
**请求方式：** POST, GET
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `numbers` | 是 | `string` | 订单number列表，多个订单用','隔开 |
**返回示例**
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "撤销订单失败原因"
}
```
## 创建车次接口
**简要描述：** 开单并创建车次
**请求 URL：** `/order/create_order_pack`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orderList` | 是 | Array[[OrderEntity](#运单参数说明)] | 运单列表 |
| `driverPhone` | 否 | `string` | 司机电话 |
**返回示例**
- 调用成功示例
```java
{
"code":200,
"data": {
"numbers":["1712051703640558"], // 创建运单号
"ids":["5a2660f3d109770010026df9"], // 运单id
"packNumber":"P171205558E431E0001" // 车次号
}
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "订单车次失败"
}
```
## 更新批次接口
**简要描述：** 更新批次
**请求 URL：** `/order/update_batch`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orderList` | 是 | Array[[OrderEntity](#运单参数说明)] |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "订单创建失败"
}
```
## 创建数据看板接口
**简要描述：** 创建数据看板
**请求 URL：** `/alogdata/create_alogdata`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `requests` | 是 | `List` | AlogdataRequest是一个对象|
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "创建失败"
}
```
## 创建数据看板库存接口
**简要描述：** 创建数据看板库存
**请求 URL：** `/alogdata/create_aloginventory`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `requests` | 是 | `List` | AloginventoryRequest|
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "创建失败"
}
```
**对象说明：**
```java
{
String warehouse;//货仓
double total;//总计
double tasking;//正在计划
double deliveryed;//已发货
double needDelivery;//未发货
double lng;//经度
double lat;//纬度
}
```
```java
{
String warehouse;//货仓
int total;//总计（数量）
double weight;//重量（吨位）
double volume;//容积率
int updated;//当天时间戳
double lng;//经度
double lat;//纬度
}
```
## 追加订单货物接口
**简要描述：** 追加订单货物
**请求 URL：** `/cargo/add`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orderNumber` | 是 | `String` | 订单号，客户单号或wms单号 |
| `cargoNumber` | 是 | `String` | 货物号 |
| `weight` | 否 | `String` | 重量 |
| `volume` | 否 | `String` | 体积 |
| `quantity` | 否 | `String` | 件数 |
| `value` | 否 | `String` | 货值 |
| `status` | 否 | `String` | 货物状态 |
| `name` | 否 | `String` | 货物名称 |
| `productModel` | 否 | `String` | 货物备注 |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "创建失败"
}
```
## 修改订单货物接口
**简要描述：** 修改订单货物
**请求 URL：** `/cargo/update`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `cargoNumber` | 是 | `String` | 货物号 |
| `weight` | 否 | `String` | 重量 |
| `volume` | 否 | `String` | 体积 |
| `quantity` | 否 | `String` | 件数 |
| `value` | 否 | `String` | 货值 |
| `status` | 否 | `String` | 货物状态 |
| `name` | 否 | `String` | 货物名称 |
| `productModel` | 否 | `String` | 货物备注 |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "创建失败"
}
```
## 删除订单货物接口
**简要描述：** 删除订单货物
**请求 URL：** `/cargo/remove`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `cargoNumber` | 是 | `String` | 货物号 |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": "true"
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "false"
}
```
## 订单订阅接口
**简要描述：** 订单订阅，请先阅读常见问题!!!
**请求 URL：** `/order/subscribe/v2`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `states` | 否 | `String` | 需要订阅的订单状态，0：已撤销，1：已下单，2：已接单，3：已装货，4：已签收；支持多选，多个状态之间用','隔开 |
| `callbackUrl` | 是 | `String` | 回调地址，以http://或https://开头，支持每个用户使用不同的回调地址 |
| `version` | 是 | `String` | v1，暂无其他版本 |
| `resultFormat` | 否 | `String` | 返回报文格式，默认是json的，可选项json,form |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": ""
}
```
- 订单订阅返回报文：
```java
{
"number ": "1609171412804505", /*订单号*/
"wmsNumber": "wmsNumber", /*出库单号，值为创建订单时的orderNumber*/
"customerOrderNumber": "111111", /*客户单号*/
"packNumber": "P20170805094004f32c20dd", /*车次号*/
"remark": "xx 订单已签收", /*订单日志*/
"state": 1, /*订单状态*/
"driver": "某司机", /*司机名称*/
"carNumber": "浙A12345", /*车牌号码*/
"phoneNumber": "13812345678", /*司机电话*/
"groupName": "xx运输队", /*车队*/
"receiptUrls":["http://oss.kuaihuoyun.com/1.png","http://oss.kuaihuoyun.com/2.png"] /*回单照片*/
}
```
## 取消订单订阅接口
**简要描述：** 取消订单订阅
**请求 URL：** `/order/unsubscribe`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": ""
}
```
## 车次订阅接口
**简要描述：** 车次订阅，请先阅读常见问题!!!
**请求 URL：** `/order/orderPack/subscribe`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `states` | 否 | `String` | 需要订阅的车次状态，19000：删除/撤销车次，40000：指派车次，40001：更新车次；支持多选，多个状态之间用','隔开 |
| `callbackUrl` | 是 | `String` | 回调地址，以http://或https://开头，支持每个用户使用不同的回调地址 |
| `resultFormat` | 否 | `String` | 返回报文格式，默认是json的，可选项json,form |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": ""
}
```
- 车次订阅返回报文：
```java
{
"carNumber": "浙WL9987", /*车牌号码*/
"groupName": "白云仓车队", /*车队*/
"orderNumbers": ["1903281059996382"], /*tms车次订单集合*/
"wmsNumbers": ["D19010300015"], /*出库单号集合，值为创建订单时的orderNumber*/
"driver": "浮夸", /*司机名称*/
"createTime": "2019-03-28 11:08:32", /*tms车次创建时间*/
"remark": "", /*备注*/
"driverPhone": "19011111111", /*司机电话*/
"state": 40000, /*19000：删除/撤销车次，40000：指派车次，40001：更新车次*/
"packNumber": "P190328563E48420011", /*tms车次号*/
"customerOrderNumbers": ["D19010300015"] /*客户单号集合*/
}
```
## 取消车次订阅接口
**简要描述：** 取消车次订阅
**请求 URL：** `/order/orderPack/unsubscribe`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": ""
}
```
## 获取组织机构列表接口
**简要描述：** 获取组织机构列表
**请求 URL：** `/organization/list`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
**返回示例**
- 调用成功示例
```java
{
"code":200,
"message":null,
"data":[
{
"nodeId":0,
"name":"总部",
"path":"0-0"
},
{
"nodeId":11,
"name":"网点1",
"path":"0-11"
},
{
"nodeId":12,
"name":"杭州网点2",
"path":"0-12"
}
]
}
```
- 调用失败示例
```java
{
"status": 500,
"message": ""
}
```
**对象说明：**
```java
{
Integer nodeId; // 机构节点id
String name; // 机构名
String path; // 父节点路径
}
```
## 添加客户接口
**简要描述：** 添加客户
**请求 URL：** `/customer/add_customers`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `customers` | 是 | `Array[CustomerEntity]` | 客户列表 |
其中CustomerEntity结构如下:
```java
{
String name; //客户名称:必填
String phone; //客户电话:必填
String address; //客户地址:必填
int type; //客户类型:必填 1发货人，2收货人
int paymentType; //支付方式:必填 1现付 2到付 3回付 4周结 5月结 6货款扣 7季度结
String remark1; //备注1:非必填
String remark2; //备注2:非必填
String remark3; //备注3:非必填
}
```
**返回示例**
- 调用成功示例
```java
{
"code":200,
"message":null,
"data": true
}
```
- 调用失败示例
```java
{
"status": 500,
"message": ""
}
```
## 创建受理单接口
**简要描述：** 受理开单
**请求 URL：** `/customer_order/create_customer_order`
**请求方式：** POST
**需要认证：** 是
**调用限制：** 批量创建受理单数一次性不得大于100
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orders` | 是 | Array[[CustomerOrderEntity](#受理单参数说明)] | 运单列表 |
**返回示例**
- 调用成功示例
调用成功但是系统中查看不到时请先阅读常见问题
```java
{
"code": 200,
"data": ["S1711151843619482"],
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "受理单创建失败"
}
```
## 更新受理单接口
**简要描述：** 修改受理单接口，没有传递的参数值将被清空
**请求 URL：** `/customer_order/update_customer_order`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `number` | 是 | `string` | 受理单号 |
| `order` | 是 | [CustomerOrderEntity](#受理单参数说明) | 受理单 |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"data": null,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "受理单创建失败"
}
```
## 批量查询受理单接口
**简要描述：** 批量查询受理单
**请求 URL：** `/customer_order/query_customer_orders`
**请求方式：** POST, GET
**需要认证：** 是
**调用频率限制：** 1秒最多一次，超过会提示操作频繁
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `page` | 是 | `int` | 页码，1开始 |
| `size` | 是 | `int` | 单页最大订单数 |
| `state` | 否 | `int` | 受理单状态，0已撤销，1000待处理，2000进行中，3000已完成，不传则查询全部状态|
| `number` | 否 | `string` | 受理单号 |
| `originalOrderNumber` | 否 | `string` | 客户单号 |
| `timeType` | 否 | `string` | 查询时间类型，created录入时间，deliveryed提货时间，appointArrived预约提货时间，signed签收时间 |
| `startDate` | 否 | `string` | 起始时间，格式"yyyy-MM-dd HH:mm:ss" |
| `endDate` | 否 | `string` | 结束时间，格式"yyyy-MM-dd HH:mm:ss" |
| `deviceNumber` | 否 | `string` | 设备号 |
| `consignerName` | 否 | `string` | 发货人姓名，模糊搜索 |
| `consignerPhone` | 否 | `string` | 发货人电话，模糊搜索 |
| `consignerAddress` | 否 | `string` | 发货人地址，模糊搜索 |
| `consigneeName` | 否 | `string` | 收货人姓名，模糊搜索 |
| `consigneePhone` | 否 | `string` | 收货人电话，模糊搜索 |
| `consigneeAddress` | 否 | `string` | 收货人地址，模糊搜索 |
| `organizationPaths` | 否 | `list` | 组织机构 |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null,
"data": {
"page": 1,
"size": 10,
"total": 11,
"elements": [
{
"order": {
"id": "5ab88c0d4b67620010302f58",
"uid": "558a2084e4b0ddab858a031e", // 用户id
"createUid": "558a2084e4b0ddab858a031e", // 制单人id
"createUserId": "15657103156", // 制单人账号
"createUsername": "冉涛12222221", // 制单人名称
"number": "S1803261358607938", // 受理单号
"originalOrderNumber": "112222", // 原始单号
"deliveryTime": 1520377500, // 提货时间
"deliveryType": null, // 提送类型，1提货，2送货
"appointArriveTime": 1520283960, // 预约送达时间
"startAddress": "洛阳", // 起始地址
"endAddress": "郑州", // 目的地址
"arrivedTime": null, //到达围栏时间
"consigner": { // 发货人
"name": "332洛阳润格商贸有限公司",
"phone": "123456789",
"address": {
"province": null,
"cityCode": null,
"city": null,
"district": null,
"name": "河南省洛阳市洛龙区36号",
"address": "河南省洛阳市洛龙区36号",
"lng": 30.2774986988,
"lat": 120.1257948758
}
},
"consignee": null, // 收货人
"cargo": { // 货物总计
"id": null,
"uid": null,
"customerOrderId": null,
"customerOrderNumber": null,
"name": "KFR-50LW/(50578)FNhAa-A2(含管)(皓雪白)(WIFI)",
"quantity": 2,
"weight": 3,
"volume": 4,
"value": 5,
"remarks": "6",
"note1": "7",
"note2": "8",
"note3": "",
"note4": "",
"note5": "",
"note6": "",
"created": null
},
"freightIn": { // 上游运费
"payType": 7,
"amount": 111
},
"uppay1": null, // 上游自定义费用1
"uppay2": null, // 上游自定义费用2
"uppay3": null, // 上游自定义费用3
"uppay4": null, // 上游自定义费用4
"uppay5": null, // 上游自定义费用5
"uppay6": null, // 上游自定义费用6
"paymentCollect": 111, // 代收货款
"receiptCount": 1, // 回单数
"remarks": "222", // 备注
"note1": null, // 自定义备注1
"note2": null, // 自定义备注2
"note3": null, // 自定义备注3
"note4": null, // 自定义备注4
"note5": null, // 自定义备注5
"note6": null, // 自定义备注6
"note7": null, // 自定义备注7
"note8": null, // 自定义备注8
"note9": null, // 自定义备注9
"note10": null, // 自定义备注10
"note11": null, // 自定义备注11
"note12": null, // 自定义备注12
"option1": null, // 自定义选项1
"option2": null, // 自定义选项2
"option3": null, // 自定义选项3
"createOrganizationPath": "0", // 开单组织机构
"ownerOrganizationPath": null, // 当前拥有者者组织机构
"assignOrganizationPaths": null, // 指派组织机构
"receiveOrganizationPath": null, // 接收方组织机构
"source": 1, // 来源 1手工录入，2批量导入，3客户下单，4接口导入
"batchNumber": null, // 导入批次号
"state": 1000, // 状态，1000待处理，2000进行中，3000已完成
"settlementParty": 2, // 上游运费结算方，1 发货人，2收货人
"totalFreightIn": 111, // 上游总运费
"freightInReceived": null,
"freightInUnreceived": 111,
"freightInState": null,
"freightInTime": null,
"paymentCollectState": null,
"paymentCollectReceived": null,
"paymentCollectTime": null,
"paymentCollectWriteoffTime": null,
"customerOrderPrintStatus": null,
"customerOrderTipsPrintStatus": null,
"receiptState": null,
"publishTime": null,
"firstSignTime": null,
"lastSignTime": null,
"currentSegmentType": null,
"reachStation": null,
"nextStation": null,
"mileage": null, //行驶里程
"mileageEstimated": 11, //预估里程
"lastUploadAddress": null,
"lastUploadTime": null,
"bindDevices": null,
"currentBindDevice": null,
"created": 1522043917,
"updated": 1522043917
},
"cargoes": [
{
"id": "5ab88c0d4b67620010302f59",
"uid": "558a2084e4b0ddab858a031e",
"customerOrderId": "5ab88c0d4b67620010302f58",
"customerOrderNumber": "S1803261358607938",
"name": "KFR-50LW/(50578)FNhAa-A2(含管)(皓雪白)(WIFI)", // 货物名称
"quantity": 2, // 数量
"weight": 3, // 重量
"volume": 4, // 体积
"value": 5, // 货值
"remarks": "6", // 备注
"note1": "7", // 货物自定义备注1
"note2": "8", // 货物自定义备注2
"note3": "", // 货物自定义备注3
"note4": "", // 货物自定义备注4
"note5": "", // 货物自定义备注5
"note6": "", // 货物自定义备注6
"created": 1522043917
}
]
}
]
}
}
```
- 调用失败示例
```java
{
"status": 500,
"message": ""
}
```
## 撤销受理单接口
**简要描述：** 批量撤销受理单
**请求 URL：** `/customer_order/cancel_customer_orders`
**请求方式：** POST, GET
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `numbers` | 是 | `string` | 订单number列表，多个订单用','隔开 |
**返回示例**
```java
{
"code": 200,
"message": null
}
```
- 调用失败示例
```java
{
"status": 500,
"message": "撤销受理单失败原因"
}
```
## 批量解绑受理单设备
**简要描述：** 批量解绑受理单设备，
**请求 URL：** `/customer_order/batch_unbind_devices`
**请求方式：** POST, GET
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orders` | 是 | `Array<受理单号>` | 受理单号列表 |
**返回示例**
```java
{
"code": 200,
"message": null,
"data": {}
}
```
- 调用失败示例
1.受理单号列表中存在未绑定设备的受理单：
```java
{
"message": "受理单S1811011025811886未绑定设备！",
"status": 500
}
```
2.受理单查询不到，请确认受理单是否存在，或者是否使用主账号调用的接口：
```java
{
"message": "受理单不存在！",
"status": 500
}
```
## 部分参数说明
#### 运单参数说明
OrderEntity结构如下:
```java
{
orderNumber (string) //接口对接时TMS系统检测订单是否存在的依据:必填 ,
consignerAddress (string) //发货人地址:必填 ,
consignerName (string) //发货人姓名:必填 ,
consignerPhone (string) //发货人电话:必填 ,
customerOrderNumber (string) //客户单号:选填 ,
batchNumber (string) //批次号：创建订单可不填，确认批次必填 ,
appointArriveTime (integer) //预约送到时间：时间戳格式，选填 ,
consigneeAddress (string) //收货人地址:可不填 ,
consigneeCity (string) //收货人所在城市:可不填 ,
consigneeDistrict (string) //收货人所在地区:可不填 ,
consigneeName (string) //收货人姓名:可不填 ,
consigneePhone (string) //收货人电话:可不填 ,
consigneeProvince (string) //收货人所在省份:可不填 ,
consignerCity (string) //发货人所在城市 ,
consignerDistrict (string) //发货人所在地区:可不填 ,
consignerProvince (string) //发货人所在省份：可不填 ,
deliveryArea (string) //第三方参数:配送区域 ,
deliveryTime (integer) //提货时间:时间戳格式 ,
deliveryType (integer) //提送类型：选填, 1自提，2送货 ,
driverPay (number) //司机运费:可不填 ,
driverPayType (integer) //司机运费支付方式:可不填, 1:现付，2到付，3回付，4周结，5月结，6货款扣，7季度结 ,
endAddress (string) //目的地:选填 ,
freightCollect (number) //代收运费：可不填 ,
lat (number) //发货人纬度 ,
lng (number) //发货人经度 ,
note (string) //备注：可不填 ,
omsNumber (string) //第三方参数:OMS单号 ,
orderType (string) //第三方参数:业务类型 ,
organizationPath (string) //组织机构：可不填 ,
ownerCode (string) //第三方参数:货主编码 ,
payMode (string) //第三方参数:付款方式 ,
paymentCollect (number) //代收货款：可不填 ,
preDeliveryTime (integer) //第三方参数:预约送货时间 ,
receiptCount (integer) //回单数量 ,
scheduleOrderCode (string) //第三方参数:调度单号 ,
shipperPay (number) //上游运费:可不填 ,
shipperPayType (integer) //上游运费支付方式:可不填, 1:现付，2到付，3回付，4周结，5月结，6货款扣，7季度结 ,
startAddress (string) //起始地:选填 ,
warehouseCode (string) //第三方参数:仓库编码 ,
wmsLocation (string) //集货位：可不填 ,
extraFields { //扩展字端：可不填,根据需要使用 ,
note1 (string) //自定义备注1 ,
note2 (string) //自定义备注2 ,
note3 (string) //自定义备注3 ,
note4 (string) //自定义备注4 ,
note5 (string) //自定义备注5 ,
note6 (string) //自定义备注6 ,
}
cargoList { //货物列表 (Array[货物请求])
cargoNumber (string) //货物编号:用于货物相关接口，需要增/删/改货物的话需要传次字段 ,
name (string) //货物名称 ,
note1 (string) //自定义备注1 ,
note2 (string) //自定义备注2 ,
note3 (string) //自定义备注3 ,
note4 (string) //自定义备注4 ,
note5 (string) //自定义备注5 ,
note6 (string) //自定义备注6 ,
orderNumber (string) //订单号 ,
productModel (string) //货物备注 ,
quantity (string) //件数 ,
status (string) //货物状态 ,
value (string) //货值 ,
volume (string) //体积 ,
weight (string) //重量
}
}
```
#### 受理单参数说明
CustomerOrderEntity结构如下:
```java
{
appointArriveTime (integer) //预约送达时间:非必填 ,
consigneeAddress (string) //收货人地址:非必填 ,
consigneeName (string) //收货人姓名:非必填 ,
consigneePhone (string) //收货人电话:非必填 ,
consignerAddress (string) //发货人地址:必填 ,
consignerName (string) //发货人姓名:必填 ,
consignerPhone (string) //发货人电话:必填 ,
deliveryTime (integer) //提货时间:非必填 ,
deliveryType (integer) //提送类型:非必填 ,
deviceNumber (string) //绑定设备号:非必填 ,
endAddress (string) //目的地:非必填 ,
//发货方经纬度
consignerLocation {
lng (double), //经度
lat (double) //纬度
},
//收货方经纬度
consigneeLocation {
lng (double), //经度
lat (double) //纬度
},
note1 (string) //自定义备注1:非必填 ,
note2 (string) //自定义备注2:非必填 ,
note3 (string) //自定义备注3:非必填 ,
note4 (string) //自定义备注4:非必填 ,
note5 (string) //自定义备注5:非必填 ,
note6 (string) //自定义备注6:非必填 ,
note7 (string) //自定义备注7:非必填 ,
note8 (string) //自定义备注8:非必填 ,
note9 (string) //自定义备注8:非必填 ,
note10 (string) //自定义备注10:非必填 ,
note11 (string) //自定义备注11:非必填 ,
note12 (string) //自定义备注12:非必填 ,
organizationPath (string) //组织机构:非必填 ,
originalOrderNumber (string) //原始单号:非必填 ,
receiptCount (integer) //回单数:非必填 ,
remarks (string) //备注:非必填 ,
shipperPay (number) //上游运费:非必填 ,
shipperPayType (integer) //上游运费支付方式:非必填 ,
startAddress (string) //起始地:非必填
cargoList {
cargoNumber (string) //货物编号:用于货物相关接口，需要增/删/改货物的话需要传此字段,
name (string) //货物名称 ,
note1 (string) //自定义备注1 ,
note2 (string) //自定义备注2 ,
note3 (string) //自定义备注3 ,
note4 (string) //自定义备注4 ,
note5 (string) //自定义备注5 ,
note6 (string) //自定义备注6 ,
productModel (string) //货物备注 ,
quantity (string) //件数 ,
status (string) //货物状态 ,
value (string) //货值 ,
volume (string) //体积 ,
weight (string) //重量
}
}
```
## 错误码说明
| 错误码 | 说明 |
|:----:|:---:|
|200|成功|
|401|授权失败|
|404| 接口不存在|
|10011| 提货时间必填|
|10012| 发货人姓名必填|
|10013| 发货人手机必填|
|10014| 发货人地址必填|
|10015| 发货人城市必填|
|10016| 城市或地址有误|
|10017| 收货人姓名必填|
|10018| 收货人手机必填|
|10019| 收货人地址必填|
|10020| 收货人城市必填|
|10021| 订单号必填|
|10022| 批次号必填|
|10023| 订单创建失败|
|10024| 传入订单列表不能为空|