# cTMS第三方接口文档
------
- [接口简介](#接口简介)
- [接口说明](#接口说明)
- [常见问题指南](PROBLEMS.md)
- [获取登陆凭证接口](#获取登陆凭证接口)
- [更新登陆凭证接口](#更新登陆凭证接口)
- [创建订单接口](#创建订单接口)
- [查询订单接口](#查询订单接口)
- [批量查询订单接口](#批量查询订单接口)
- [撤销订单接口](#撤销订单接口)
- [撤销订单接口v2](#撤销订单接口v2)
- [创建车次接口](#创建车次接口)
- [更新批次接口](#更新批次接口)
- [创建数据看板接口](#创建数据看板接口)
- [创建数据看板库存接口](#创建数据看板库存接口)
- [追加订单货物接口](#追加订单货物接口)
- [修改订单货物接口](#修改订单货物接口)
- [删除订单货物接口](#删除订单货物接口)
- [订单订阅接口](#订单订阅接口)
- [订单订阅接口v2](#订单订阅接口v2)
- [取消订单订阅接口](#取消订单订阅接口)
- [车次订阅接口](#车次订阅接口)
- [取消车次订阅接口](#取消车次订阅接口)
- [获取组织机构列表接口](#获取组织机构列表接口)
- [添加客户接口](#添加客户接口)
- [创建受理单接口](#创建受理单接口)
- [更新受理单接口](#更新受理单接口)
- [批量查询受理单接口](#批量查询受理单接口)
- [撤销受理单接口](#撤销受理单接口)
- [错误码说明](#错误码说明)
- [测试代码](#测试代码)
## 接口简介
本文档为CTMS第三方开放接口文档，操作流程为：
1. 注册并开通CTMS账号（测试环境账号联系对接人员）；
2. 获取接口访问令牌（token令牌只需获取一次即可，有效期为一年）
3. 调用CTMS提供的接口（需要先获取令牌（access_token））；
- **接口地址**：测试环境=http://api.test.56ctms.com ，正式环境=http://api.56ctms.com
- **获取接口访问令牌**： /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
- **调试地址**： /swagger-ui.html
## 接口说明
所有接口支持RESTful的方式访问，返回结果首先判断http状态码，有如下几种情况：
1. 404表示接口不存在，请检查调用的接口地址，协议的格式是否正确
2. 401表示授权失败，需要重新登陆获取access_token
3. 200，201，20*表示调用接口成功，返回body中调用结果，是http JSON格式的，包含以下字段
- **code**：状态码，取值有 200，非200；200 表示接口调用成功， 非200 表示接口调用失败
- **message**：错误信息，当接口调用失败（状态码为 非200）时，返回的错误信息
- **data**：返回数据，接口调用成功（状态码为 200）之后返回的数据
## SDK地址
使用java开发的，可以使用SDK调用接口，SDK地址：https://gitee.com/kuaihuoyun_ctms/ctms-sdk-demo.git
可以将代码打成jar包，或者使用maven依赖：
```
<dependency>
<groupId>com.kuaihuoyun.ctms</groupId>
<artifactId>ctms-sdk</artifactId>
<version>1.0.1</version>
</dependency>
```
## 获取登陆凭证接口
**简要描述：** 获取登陆凭证
**请求 URL：** `/user/generate_access_token`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `userName` | 是 | `账号` | |
| `password` | 是 | `密码` | |
**返回示例**
- 调用成功示例
```
{
"body":
{
"accessToken":"5dcb8779-a714-4a52-9956-857905e16b9e",
"refreshToken":"d062ebe7-2719-4e82-b822-5ec22714937e"
},
"status":200
}
```
- 调用失败示例
```
{
"status": 500,
"message": "账号或密码不正确"
}
```
## 更新登陆凭证接口
**简要描述：** 更新登陆凭证
**请求 URL：** `/user/refresh_access_token`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `userName` | 是 | `账号` | |
| `refreshToken` | 是 | `刷新凭证` | |
**返回示例**
- 调用成功示例
```
{
"body":
{
"accessToken":"5dcb8779-a714-4a52-9956-857905e16b9e",
"refreshToken":"d062ebe7-2719-4e82-b822-5ec22714937e"
},
"status":200
}
```
- 调用失败示例
```
{
"status": 500,
"message": "账号或刷新凭证不正确"
}
```
## 创建订单接口
**简要描述：** 开单
**请求 URL：** `/order/create_order`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orderList` | 是 | `Array[OrderEntity]` | 运单列表 |
```
开单报文结构如下:
{
"orderList": [
{
"appointArriveTime": 0,
"batchNumber": "string",
"consigneeAddress": "string",
"consigneeCity": "string",
"consigneeDistrict": "string",
"consigneeName": "string",
"consigneePhone": "string",
"consigneeProvince": "string",
"consignerAddress": "string",
"consignerCity": "string",
"consignerDistrict": "string",
"consignerName": "string",
"consignerPhone": "string",
"consignerProvince": "string",
"customerOrderNumber": "string",
"deliveryArea": "string",
"deliveryTime": 0,
"driverPay": 0,
"endAddress": "string",
"extraFields": {},
"lat": 0,
"lng": 0,
"note": "string",
"omsNumber": "string",
"orderNumber": "string",
"orderType": "string",
"organizationPath": "string",
"ownerCode": "string",
"payMode": "string",
"paymentCollect": 0,
"preDeliveryTime": 0,
"scheduleOrderCode": "string",
"shipperPay": 0,
"shipperPayType": 1,
"startAddress": "string",
"warehouseCode": "string",
"wmsLocation": "string",
"cargoList": [
{
"cargoNumber": "string",
"name": "string",
"note1": "string",
"note2": "string",
"note3": "string",
"note4": "string",
"note5": "string",
"note6": "string",
"orderNumber": "string",
"productModel": "string",
"quantity": "string",
"status": "string",
"value": "string",
"volume": "string",
"weight": "string"
}
]
}
]
}
```
```
其中OrderEntity结构如下:
OrderEntity {
private String batchNumber;//批次号：创建订单可不填，确认批次必填
private String orderNumber;//订单号:两边订单唯一依据(必填)
private String wmsLocation; //集货位
private Integer deliveryTime; //提货时间:时间戳格式(必填)
private Integer deliveryType; //提送类型：选填, 1自提，2送货
private Integer appointArriveTime; //预约送到时间：时间戳格式，选填
private String customerOrderNumber; // 客户单号
private String startAddress; // 起始地
private String endAddress; // 目的地
private String consignerName;//发货人姓名(必填)
private String consignerPhone;//发货人电话
private String consignerAddress;//发货人地址(必填)
private String consignerProvince; // 发货人所在省份
private String consignerCity;//发货人所在城市(必填)
private String consignerDistrict;//发货人所在地区
private String consigneeName;//收货人姓名
private String consigneePhone;//收货人电话
private String consigneeAddress;//收货人地址
private String consigneeProvince; // 收货人所在省份
private String consigneeCity;//收货人所在城市
private String consigneeDistrict;//收货人所在地区
private Double shipperPay;//上游运费
private Integer shipperPayType; //上游运费支付方式:可不填, 1:现付，2到付，3回付，4周结，5月结，6货款扣，7季度结
private Double driverPay; //司机运费
private Integer driverPayType; //司机运费支付方式:可不填, 1:现付，2到付，3回付，4周结，5月结，6货款扣，7季度结
private Integer receiptCount; //回单数量
private Double freightCollect; //代收运费：可不填
private Double paymentCollect; //代收货款：可不填
private String warehouseCode;//第三方参数:仓库编码
private String ownerCode; //第三方参数:货主编码
private String scheduleOrderCode; //第三方参数:调度单号
private String orderType; //第三方参数:业务类型
private String deliveryArea; //第三方参数:配送区域
private String omsNumber; //第三方参数:oms订单号
private Integer preDeliveryTime; //第三方参数:预约送货时间
private String payMode; //第三方参数:付款方式
private String note; //备注：可不填
private Map<String, Object> extraFields; //扩展字端：可不填
private String organizationPath; // 所属组织路径, 可不填
private Double lng; //发货人经度
private Double lat; //发货人纬度
//货物列表
private List<CargoRequest> cargoList{
private String orderNumber;//订单号
private String cargoNumber;//货物号
private String weight;//重量
private String volume;//体积
private String quantity;//件数
private String value;//货值
private String status;//货物状态
private String name;//货物名称
private String productModel;// 货物备注
private String note1; // 自定义备注1
private String note2; // 自定义备注2
private String note3; // 自定义备注3
private String note4; // 自定义备注4
private String note5; // 自定义备注5
private String note6; // 自定义备注6
}
}
```
**返回示例**
- 调用成功示例
```
{
"code": 200,
"data": ["1712051703640558"],
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "订单创建失败"
}
```
## 查询订单接口
**简要描述：** 查询订单
**请求 URL：** `/order/find_order`
**请求方式：** get
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orderNumber` | 否 | `String` | 订单号 |
| `phoneNumber` | 否 | `String` | 发货人手机号 |
| `customerNumber` | 否 | `String` | 客户自定义单号 |
||||不传任何参数则查询所有|
**返回示例**
- 调用成功示例
```
{
"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,／／订单创建时间
}
]
}
```
- 调用失败示例
```
{
"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` | 司机车牌号码，模糊搜索 |
**返回示例**
- 调用成功示例
```
{
"code": 200,
"data": {
"total": 220,
"size": 1,
"elements": [
{
"uid": "558a2084e4b0ddab858a031e", // 主账号uid
"operator": "558a2084e4b0ddab858a031e", // 操作人uid
"deliveryTime": 1504526400, //提货时间
"source": 1, // 订单来源，1手工录入，2标准导入，4接口导入
"customerOrderNumber": "", // 客户单号
"startAddress": "", // 起始地址
"endAddress": "", // 目的地址
"waybillState": 1, // 运单状态，state为2000时才回有值，1已下单，2已接单，3已装货，4已签收
"consigner": { // 发货人
"address": { // 发货地址
"address": "河南省洛阳市洛龙区36号",
"lng": 30.2774986988,
"name": "河南省洛阳市洛龙区36号",
"lat": 120.1257948758
},
"phone": "123456789", // 发货人电话
"name": "332洛阳润格商贸有限公司" // 发货人姓名
},
"consignees" : [{ // 收货人
"address": { // 收货地址
"address": "河南省洛阳市洛龙区36号",
"lng": 30.2774986988,
"name": "河南省洛阳市洛龙区36号",
"lat": 120.1257948758
},
"phone": "123456789", // 收货人电话
"name": "332洛阳润格商贸有限公司" // 收货人姓名
},
],
"packNumber" : "P170714595E4D5D0007", // 车次号
"number": "1709041936863748", // 运单号
"appointArriveTime": 1504530600, // 预约送达时间
"id": "59ad3aa819a356001132aa98", // 运单id
"state": 1000, // 运单状态
"createUid": "558a2084e4b0ddab858a031e",
"freightIn": { // 上游运费
"amount": 1, // 上游费用
"payType": 1 // 上游费用支付方式， 1现付，2到付，3回付，4周结，5月结
},
"freightOut": { // 司机运费
"amount": 1, // 司机费用
"payType": 5 // 上游费用支付方式
},
"paymentCollect": 0, // 代收运费
"receiptCount": 1, // 回单数量
"needReceipt": 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
},
"created": 1504524968, // 录入时间
"updated": 1506392577, // 更新时间
"publishTime" : 1500012379, // 下单时间
"receiveTime" : 1500012379, // 接单时间
"shipmentTime" : 1500019019, // 装货时间
"signedTime" : 1500019019, // 签收时间
}
],
"page": 1
}
}
```
- 调用失败示例
```
{
"status": 500,
"message": ""
}
```
## 撤销订单接口
**简要描述：** 批量撤销订单
**请求 URL：** `/order/cancel_orders`
**请求方式：** POST, GET form提交
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `numbers` | 是 | `string` | 订单number列表，多个订单用','隔开 |
**返回示例**
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "撤销订单失败原因"
}
```
## 撤销订单接口v2
**简要描述：** 批量撤销订单v2
**请求 URL：** `/order/cancel_orders/v2`
**请求方式：** POST, GET
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `numbers` | 是 | `string` | 订单number列表，多个订单用','隔开 |
**返回示例**
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "撤销订单失败原因"
}
```
## 创建车次接口
**简要描述：** 开单并创建车次
**请求 URL：** `/order/create_order_pack`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orderList` | 是 | `Array[OrderEntity]` | 运单列表 |
| `driverPhone` | 否 | `string` | 司机电话 |
```
driverPhone; //接单司机，支持批量，多个司机之间用逗号隔开
orderList{
private String batchNumber;//批次号：创建订单可不填，确认批次必填
private String orderNumber;//订单号:两边订单唯一依据(必填)
private String wmsLocation; //集货位
private Integer deliveryTime; //提货时间:时间戳格式(必填)
private Integer deliveryType; //提送类型：选填, 1自提，2送货
private Integer appointArriveTime; //预约送到时间：时间戳格式，选填
private String customerOrderNumber; // 客户单号
private String startAddress; // 起始地
private String endAddress; // 目的地
private String consignerName;//发货人姓名(必填)
private String consignerPhone;//发货人电话
private String consignerAddress;//发货人地址(必填)
private String consignerProvince; // 发货人所在省份
private String consignerCity;//发货人所在城市(必填)
private String consignerDistrict;//发货人所在地区
private String consigneeName;//收货人姓名
private String consigneePhone;//收货人电话
private String consigneeAddress;//收货人地址
private String consigneeProvince; // 收货人所在省份
private String consigneeCity;//收货人所在城市
private String consigneeDistrict;//收货人所在地区
private Double shipperPay;//上游运费
private Integer shipperPayType; //上游运费支付方式:可不填, 1:现付，2到付，3回付，4周结，5月结，6货款扣，7季度结
private Double driverPay; //司机运费
private Integer driverPayType; //司机运费支付方式:可不填, 1:现付，2到付，3回付，4周结，5月结，6货款扣，7季度结
private Integer receiptCount; //回单数量
private Double freightCollect; //代收运费：可不填
private Double paymentCollect; //代收货款：可不填
private String warehouseCode;//第三方参数:仓库编码
private String ownerCode; //第三方参数:货主编码
private String scheduleOrderCode; //第三方参数:调度单号
private String orderType; //第三方参数:业务类型
private String deliveryArea; //第三方参数:配送区域
private String omsNumber; //第三方参数:oms订单号
private Integer preDeliveryTime; //第三方参数:预约送货时间
private String payMode; //第三方参数:付款方式
private String note; //备注：可不填
private Map<String, Object> extraFields; //扩展字端：可不填
private String organizationPath; // 所属组织路径, 可不填
private Double lng; //发货人经度
private Double lat; //发货人纬度
//货物列表
private List<CargoRequest> cargoList{
private String orderNumber;//订单号
private String cargoNumber;//货物号
private String weight;//重量
private String volume;//体积
private String quantity;//件数
private String value;//货值
private String status;//货物状态
private String name;//货物名称
private String productModel;// 货物备注
private String note1; // 自定义备注1
private String note2; // 自定义备注2
private String note3; // 自定义备注3
private String note4; // 自定义备注4
private String note5; // 自定义备注5
private String note6; // 自定义备注6
}
}
```
**返回示例**
- 调用成功示例
```
{"code":200,
"data": {
"numbers":["1712051703640558"], // 创建运单号
"ids":["5a2660f3d109770010026df9"], // 运单id
"packNumber":"P171205558E431E0001" // 车次号
}
}
```
- 调用失败示例
```
{
"code": 500,
"message": "订单车次失败"
}
```
## 更新批次接口
**简要描述：** 更新批次
**请求 URL：** `/order/update_batch`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orderList` | 是 | `Array[OrderEntity]` | |
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"status": 500,
"message": "订单创建失败"
}
```
**对象说明：**
```
public class OrderRequest implements Serializable {
List<OrderEntity> orderList;
}
```
## 创建数据看板接口
**简要描述：** 创建数据看板
**请求 URL：** `/alogdata/create_alogdata`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `requests` | 是 | `List<AlogdataRequest>` | AlogdataRequest是一个对象|
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "创建失败"
}
```
## 创建数据看板库存接口
**简要描述：** 创建数据看板库存
**请求 URL：** `/alogdata/create_aloginventory`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `requests` | 是 | `List<AloginventoryRequest>` | AloginventoryRequest|
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "创建失败"
}
```
**对象说明：**
```
public class AlogdataRequest {
private String warehouse;//货仓
private double total;//总计
private double tasking;//正在计划
private double deliveryed;//已发货
private double needDelivery;//未发货
private double lng;//经度
private double lat;//纬度
}
```
```
public class AloginventoryRequest {
private String warehouse;//货仓
private int total;//总计（数量）
private double weight;//重量（吨位）
private double volume;//容积率
private int updated;//当天时间戳
private double lng;//经度
private 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` | 货物备注 |
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "创建失败"
}
```
## 修改订单货物接口
**简要描述：** 修改订单货物
**请求 URL：** `/cargo/update`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `cargoNumber` | 是 | `String` | 货物号 |
| `weight` | 否 | `String` | 重量 |
| `volume` | 否 | `String` | 体积 |
| `quantity` | 否 | `String` | 件数 |
| `value` | 否 | `String` | 货值 |
| `status` | 否 | `String` | 货物状态 |
| `name` | 否 | `String` | 货物名称 |
| `productModel` | 否 | `String` | 货物备注 |
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "创建失败"
}
```
## 删除订单货物接口
**简要描述：** 删除订单货物
**请求 URL：** `/cargo/remove`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `cargoNumber` | 是 | `String` | 货物号 |
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "创建失败"
}
```
**对象说明：**
```
public class CargoRequest {
private String orderNumber;//订单号
private String cargoNumber;//货物号
private String weight;//重量
private String volume;//体积
private String quantity;//件数
private String value;//货值
private String status;//货物状态
private String name;//货物名称
private String productModel;//货物备注
}
```
## 订单订阅接口
**简要描述：** 订单订阅
**请求 URL：** `/order/subscribe`
**请求方式：** POST, form提交
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `states` | 否 | `String` | 需要订阅的订单状态，0：已撤销，1：已下单，2：已接单，3：已装货，4：已签收；支持多选，多个状态之间用','隔开 |
| `callbackUrl` | 是 | `String` | 回调地址，以http://或https://开头，支持每个用户使用不同的回调地址 |
| `version` | 是 | `String` | 版本号，v1 |
| `resultFormat` | 否 | `String` | 返回报文格式，默认是json的，可选项json,form |
| `signMode` | 否 | `String` | 签名方式，v1 |
| `appKey` | 否 | `String` | 签名appKey，signMode不为空时必填 |
| `appSecret` | 否 | `String` | 签名appSecret，signMode不为空时必填 |
| `method` | 否 | `String` | 签名method，signMode不为空时必填 |
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": ""
}
```
- 订单订阅返回报文：
```
{
"number ": "1609171412804505", /*订单号*/
"wmsNumber": "wmsNumber", /*出库单号*/
"customerOrderNumber": "111111", /*客户单号*/
"packNumber": "P20170805094004f32c20dd", /*车次号*/
"remark": "xx 订单已签收", /*订单日志*/
"state": 1, /*订单状态*/
"driver": "某司机", /*司机名称*/
"carNumber": "浙A12345", /*车牌号码*/
"phoneNumber": "13812345678" /*司机电话*/
}
```
## 订单订阅接口v2
**简要描述：** 订单订阅
**请求 URL：** `/order/subscribe/v2`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `states` | 否 | `String` | 需要订阅的订单状态，0：已撤销，1：已下单，2：已接单，3：已装货，4：已签收；支持多选，多个状态之间用','隔开 |
| `callbackUrl` | 是 | `String` | 回调地址，以http://或https://开头，支持每个用户使用不同的回调地址 |
| `version` | 是 | `String` | 版本号，v1 |
| `resultFormat` | 否 | `String` | 返回报文格式，默认是json的，可选项json,form |
| `signMode` | 否 | `String` | 签名方式，v1 |
| `appKey` | 否 | `String` | 签名appKey，signMode不为空时必填 |
| `appSecret` | 否 | `String` | 签名appSecret，signMode不为空时必填 |
| `method` | 否 | `String` | 签名method，signMode不为空时必填 |
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": ""
}
```
- 订单订阅返回报文：
```
{
"number ": "1609171412804505", /*订单号*/
"wmsNumber": "wmsNumber", /*出库单号*/
"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"] /*回单照片*/
"abnormal":true, /*是否异常*/
"signer":"签收人",
"note":"异常原因"
}
```
## 取消订单订阅接口
**简要描述：** 取消订单订阅
**请求 URL：** `/order/unsubscribe`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": ""
}
```
## 车次订阅接口
**简要描述：** 车次订阅
**请求 URL：** `/order/orderPack/subscribe`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `states` | 否 | `String` | 需要订阅的车次状态，19000：删除/撤销车次，40000：指派车次，40001：更新车次；支持多选，多个状态之间用','隔开 |
| `callbackUrl` | 是 | `String` | 回调地址，以http://或https://开头，支持每个用户使用不同的回调地址 |
| `version` | 否 | `String` | 版本号，v1 |
| `resultFormat` | 否 | `String` | 返回报文格式，默认是json的，可选项json,form |
| `signMode` | 否 | `String` | 签名方式，v1 |
| `appKey` | 否 | `String` | 签名appKey，signMode不为空时必填 |
| `appSecret` | 否 | `String` | 签名appSecret，signMode不为空时必填 |
| `method` | 否 | `String` | 签名method，signMode不为空时必填 |
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": ""
}
```
- 车次订阅返回报文：
```
{
"packNumber ": "P1609171412804505", /*tms车次号*/
"createTime": "2018-05-28 15:32:12", /*tms车次创建时间*/
"state": 19000, /*19000：删除/撤销车次，40000：指派车次，40001：更新车次*/
"driver": "某司机", /*司机名称*/
"carNumber": "浙A12345", /*车牌号码*/
"groupName": "xx运输队", /*车队*/
"driverPhone": "13812345678", /*司机电话*/
"orderNumbers":["2323424234234","609171412804505"] /*tms车次订单集合*/
"wmsNumbers" : "wmsNumber",/*出库单号集合*/
"customerOrderNumbers": "xxx", /*客户单号集合*/
"remark":"232323", /*备注*/
}
```
## 取消车次订阅接口
**简要描述：** 取消车次订阅
**请求 URL：** `/order/orderPack/unsubscribe`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
**返回示例**
- 调用成功示例
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": ""
}
```
## 获取组织机构列表接口
**简要描述：** 获取组织机构列表
**请求 URL：** `/organization/list`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
**返回示例**
- 调用成功示例
```
{
"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"
}
]
}
```
- 调用失败示例
```
{
"code": 500,
"message": ""
}
```
**对象说明：**
```
public class OrganizationEntity implements Serializable {
private Integer nodeId; // 机构节点id
private String name; // 机构名
private String path; // 父节点路径
}
```
## 添加客户接口
**简要描述：** 添加客户
**请求 URL：** `/customer/add_customers`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `customers` | 是 | `Array[CustomerEntity]` | 客户列表 |
```
其中CustomerEntity结构如下:
CustomerEntity {
private String name; //客户名称:必填
private String phone; //客户电话:必填
private String address; //客户地址:必填
private int type; //客户类型:必填 1发货人，2收货人
private int paymentType; //支付方式:必填 1现付 2到付 3回付 4周结 5月结 6货款扣 7季度结
private String remark1; //备注1:非必填
private String remark2; //备注2:非必填
private String remark3; //备注3:非必填
}
```
**返回示例**
- 调用成功示例
```
{
"code":200,
"message":null,
"data": true
}
```
- 调用失败示例
```
{
"code": 500,
"message": ""
}
```
## 创建受理单接口
**简要描述：** 受理开单
**请求 URL：** `/customer_order/create_customer_order`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `orders` | 是 | `Array[CustomerOrderEntity]` | 运单列表 |
```
其中CustomerOrderEntity结构如下:
CustomerOrderEntity {
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:非必填 ,
note10 (string): 自定义备注10:非必填 ,
note11 (string): 自定义备注11:非必填 ,
note12 (string): 自定义备注12:非必填 ,
note2 (string): 自定义备注2:非必填 ,
note3 (string): 自定义备注3:非必填 ,
note4 (string): 自定义备注4:非必填 ,
note5 (string): 自定义备注5:非必填 ,
note6 (string): 自定义备注6:非必填 ,
note7 (string): 自定义备注7:非必填 ,
note8 (string): 自定义备注8:非必填 ,
note9 (string): 自定义备注8:非必填 ,
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 ,
orderNumber (string): 订单号 ,
productModel (string): 货物备注 ,
quantity (string): 件数 ,
status (string): 货物状态 ,
value (string): 货值 ,
volume (string): 体积 ,
weight (string): 重量
}
}
```
**返回示例**
- 调用成功示例
```
{
"code": 200,
"data": ["S1711151843619482"],
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "受理单创建失败"
}
```
## 更新受理单接口
**简要描述：** 修改受理单
**请求 URL：** `/customer_order/update_customer_order`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `number` | 是 | `string` | 受理单号 |
| `order` | 是 | `CustomerOrderEntity` | 受理单 |
**返回示例**
- 调用成功示例
```
{
"code": 200,
"data": null,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "受理单创建失败"
}
```
## 批量查询受理单接口
**简要描述：** 批量查询受理单
**请求 URL：** `/customer_order/query_customer_orders`
**请求方式：** POST, GET
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `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` | 组织机构 |
**返回示例**
- 调用成功示例
```
{
"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
}
]
}
]
}
}
```
- 调用失败示例
```
{
"status": 500,
"message": ""
}
```
## 撤销受理单接口
**简要描述：** 批量撤销受理单
**请求 URL：** `/customer_order/cancel_customer_orders`
**请求方式：** POST, GET
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `numbers` | 是 | `string` | 订单number列表，多个订单用','隔开 |
**返回示例**
```
{
"code": 200,
"message": null
}
```
- 调用失败示例
```
{
"code": 500,
"message": "撤销受理单失败原因"
}
```
## 错误码说明
| 错误码 | 说明 |
|:----:|:---:|
|200|成功|
|401|授权失败|
|404| 接口不存在|
|10011| 提货时间必填|
|10012| 发货人姓名必填|
|10013| 发货人手机必填|
|10014| 发货人地址必填|
|10015| 发货人城市必填|
|10016| 城市或地址有误|
|10017| 收货人姓名必填|
|10018| 收货人手机必填|
|10019| 收货人地址必填|
|10020| 收货人城市必填|
|10021| 订单号必填|
|10022| 批次号必填|
|10023| 订单创建失败|
|10024| 传入订单列表不能为空|
## 测试代码
```
接口测试例子
TestMain.java
oauth授权例子
1：mvn clean jetty:run
2：用浏览器访问：http://localhost:9090
```