# cTMS第三方接口文档 ------ - [接口简介(请仔细阅读!)](#接口简介) - [接口说明](#接口说明) - [常见问题指南(有问题先看这!)](PROBLEMS.md) - [获取登陆凭证接口](#获取登陆凭证接口) - [更新登陆凭证接口](#更新登陆凭证接口) - [创建订单接口](#创建订单接口) - [查询订单接口](#查询订单接口) - [批量查询订单接口](#批量查询订单接口) - [撤销订单接口](#撤销订单接口) - [撤销订单接口v2](#撤销订单接口v2) - [创建车次接口](#创建车次接口) - [更新批次接口](#更新批次接口) - [创建数据看板接口](#创建数据看板接口) - [创建数据看板库存接口](#创建数据看板库存接口) - [追加订单货物接口](#追加订单货物接口) - [修改订单货物接口](#修改订单货物接口) - [删除订单货物接口](#删除订单货物接口) - [订单订阅接口](#订单订阅接口) - [订单订阅接口v2](#订单订阅接口v2) - [取消订单订阅接口](#取消订单订阅接口) - [车次订阅接口](#车次订阅接口) - [取消车次订阅接口](#取消车次订阅接口) - [获取组织机构列表接口](#获取组织机构列表接口) - [添加客户接口](#添加客户接口) - [创建受理单接口](#创建受理单接口) - [更新受理单接口](#更新受理单接口) - [批量查询受理单接口](#批量查询受理单接口) - [撤销受理单接口](#撤销受理单接口) - [批量解绑受理单设备](#批量解绑受理单设备) - [错误码说明](#错误码说明) - [测试代码](#测试代码) ## 接口简介 本文档为CTMS第三方开放接口文档，操作流程为： 1. 注册并开通CTMS账号（测试环境账号联系对接人员）； 2. 获取接口访问令牌（token令牌只需获取一次即可，有效期为一年！）； 3. 调用CTMS提供的接口（需要先获取令牌（access_token））； 4. 所有接口需要使用主账号调用，类似创建订单之类的接口需要使用主账号调用以后系统中才能看到！
请使用主账号获取对应的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依赖： ``` com.kuaihuoyun.ctms ctms-sdk 1.0.1 ``` ## 获取登陆凭证接口 **简要描述：** 获取登陆凭证 **请求 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]` | 运单列表 | ``` 其中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 extraFields; //扩展字端：可不填 private String organizationPath; // 所属组织路径, 可不填 private Double lng; //发货人经度 private Double lat; //发货人纬度 //货物列表 private List 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 extraFields; //扩展字端：可不填 private String organizationPath; // 所属组织路径, 可不填 private Double lng; //发货人经度 private Double lat; //发货人纬度 //货物列表 private List 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 orderList; } ``` ## 创建数据看板接口 **简要描述：** 创建数据看板 **请求 URL：** `/alogdata/create_alogdata` **请求方式：** POST **需要认证：** 是 **请求参数：** | 参数名 | 必选 | 类型 | 说明 | |:----:|:---:|:-----:|:-----:| | `requests` | 是 | `List` | AlogdataRequest是一个对象| **返回示例** - 调用成功示例 ``` { "code": 200, "message": null } ``` - 调用失败示例 ``` { "code": 500, "message": "创建失败" } ``` ## 创建数据看板库存接口 **简要描述：** 创建数据看板库存 **请求 URL：** `/alogdata/create_aloginventory` **请求方式：** POST **需要认证：** 是 **请求参数：** | 参数名 | 必选 | 类型 | 说明 | |:----:|:---:|:-----:|:-----:| | `requests` | 是 | `List` | 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": "撤销受理单失败原因" } ``` ## 批量解绑受理单设备 **简要描述：** 批量解绑受理单设备， **请求 URL：** `/customer_order/batch_unbind_devices` **请求方式：** POST, GET **需要认证：** 是 **请求参数：** | 参数名 | 必选 | 类型 | 说明 | |:----:|:---:|:-----:|:-----:| | `orders` | 是 | `Array<受理单号>` | 受理单号列表 | **返回示例** ``` { "code": 200, "message": null, "data": {} } ``` - 调用失败示例 ``` 1.受理单号列表中存在未绑定设备的受理单： { "message": "受理单S1811011025811886未绑定设备！", "status": 500 } 2.受理单查询不到，请确认受理单是否存在，或者是否使用主账号调用的接口： { "message": "受理单不存在！", "status": 500 } ``` ## 错误码说明 | 错误码 | 说明 | |:----:|:---:| |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 ```