Home Explore Help
Register Sign In
gongmingwei
/
ctms-sdk-demo
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki

TMS开放接口文档

Tree: 1247559e5f
Branches Tags
ctms-sdk-demo
gmw 1247559e5f 更新接口文档：去除sdk，已不再维护 6 years ago
image 74f8a6c211 更新文档 6 years ago
src 084823410a 更新接口文档 6 years ago
.gitignore b043d3b7c7 1 6 years ago
PROBLEMS.md 2d4bdb16b5 更新接口文档 6 years ago
README.md 1247559e5f 更新接口文档：去除sdk，已不再维护 6 years ago
pom.xml b043d3b7c7 1 6 years ago

README.md

cTMS第三方接口文档

接口简介

本文档为CTMS第三方开放接口文档，操作流程为：

  1. 注册并开通CTMS账号（测试环境账号联系对接人员）；
  2. 获取接口访问令牌（token令牌只需获取一次即可，有效期为一年！）；
  3. 调用CTMS提供的接口（需要先获取令牌（access_token））；
  4. 所有接口需要使用主账号调用，类似创建订单之类的接口需要使用主账号调用以后系统中才能看到！
    请使用主账号获取对应的token再调用其他接口!!!

接口说明

所有接口支持RESTful的方式访问，返回结果首先判断http状态码，有如下几种情况：

  1. 404表示接口不存在，请检查调用的接口地址，协议的格式是否正确
  2. 401表示授权失败，需要重新登陆获取access_token
  3. 200，201，20*表示调用接口成功，返回body中调用结果，是http JSON格式的，包含以下字段
  • code：状态码，取值有 200，非200；200 表示接口调用成功， 非200 表示接口调用失败
  • message：错误信息，当接口调用失败（状态码为 非200）时，返回的错误信息
  • data：返回数据，接口调用成功（状态码为 200）之后返回的数据

获取登陆凭证接口

简要描述： 获取登陆凭证

请求 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;//订单号:客户系统和TMS系统中订单关联的唯一依据(必填)
        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; //备注扩展字端：可不填,key的值对应note1-6
        private String organizationPath; // 所属组织路径, 可不填
        private Double lng; //发货人经度
        private Double lat; //发货人纬度
        //货物列表
        private List<CargoRequest> cargoList{
                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": { //备注扩展字端：可不填,key的值对应note1-6
                    "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;//订单号:客户系统和TMS系统中订单关联的唯一依据(必填)
        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; //备注扩展字端：可不填,key的值对应note1-6
        private String organizationPath; // 所属组织路径, 可不填
        private Double lng; //发货人经度
        private Double lat; //发货人纬度
        //货物列表
        private List<CargoRequest> cargoList{
                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;//货物备注
}

订单订阅接口

简要描述： 订单订阅，请使用v2接口

请求 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" /*司机电话*/ }

注意事项

回调地址的返回结果中，如果成功要在返回信息中包含"code": 200，系统会根据这个值来判断消息是否投递成功，否则会重新进行投递

订单订阅接口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":"异常原因" }

注意事项

回调地址的返回结果中，如果成功要在返回信息中包含"code": 200，系统会根据这个值来判断消息是否投递成功，否则会重新进行投递

取消订单订阅接口

简要描述： 取消订单订阅

请求 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", /*备注*/ }

注意事项

回调地址的返回结果中，如果成功要在返回信息中包含"code": 200，系统会根据这个值来判断消息是否投递成功，否则会重新进行投递

取消车次订阅接口

简要描述： 取消车次订阅

请求 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 ,
        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