则一订单对接API

则一提供了不同规范的API，调用则一订单服务端API前，需了解开发前须知及调用流程。本文提供了调用则一订单服务端API示例，供开发者参考。

白名单

则一服务端API接口访问有IP白名单限制，需要接口调用方提供调用API的服务器IP地址。

数据加签

采用md5(32位小写)算法生成签名 appKey(则一提供) + appSecret(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(请求数据)

数据加密

数据加密采用AES算法 加密模式： CBC 填充方式：PKCS5Padding 偏移量：iv(则一提供) 加密内容：appKey(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(加密数据) 密钥： appSecret(则一提供) 输出：base64 字符集：utf-8 注：无敏感数据则无需加密

获取访问凭证

概述

调用则一服务API时，都需要先获取对应权限类型的访问凭证accessToken。访问凭证（accessToken）是由则一权限系统颁发的，用来校验调用者的身份信息，确保调用者具有要执行的操作的权限。 说明： 在使用accessToken时，请注意：

• accessToken的有效期默认为30天，有效期内重复获取会返回相同结果，过期后获取会返回新的accessToken。
• 开发者需要缓存accessToken，用于后续接口的调用。不能频繁调用获取accessToken接口，否则会受到频率拦截。
• 当调用业务API时，如果返回状态码为401，则说明accessToken不正确或已过期，这时需要重新获取accessToken后再调用对应的API。

接口信息

请求方式：

post

请求地址：

• 生产：https://gw.shjiuze.cn/auth-service-api/login/password
• 测试：https://test.shjiuze.cn/auth-service-api/login/password

Body参数

返回参数

请求示例

Http方式

​x
POST /auth-service-api/login/password HTTP/1.1
Host:test.shjiuze.cn
Content-Type:application/json

{
  "username" : "zeyi",
  "password" : "test1111"
}

Java-sdk方式 下载SDK

xxxxxxxxxx
public class Sample {
    public static void main(String[] args_) {
        String appKey = "appkey";
        String appSecret = "appSecret";
        ZYClient zyClient = new ZYClient(appKey, appSecret);
        ZYTokenRequestDto zyTokenRequest = new ZYTokenRequestDto();
        zyTokenRequest.setUsername("zeyi");
        zyTokenRequest.setPassword("test1111");
        String body = gson.toJson(zyTokenRequest);
        HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + Constants.TOKEN_PATH, body);
        if(httpResponseData == null) {
            throw new TokenException("则一Token请求失败,返回为空!");
        }
        ZYResponse<ZYTokenDto> zyResponse = gson.fromJson(httpResponseData.getBody(), new      TypeToken<ZYResponse<ZYTokenDto>>(){}.getType());
        if(!Boolean.TRUE.equals(zyResponse.isSuccess())) {    
            throw new TokenException("则一Token请求返回失败!" + zyResponse.getMessage());
        }
        if(zyResponse.getResult() == null) {    
            throw new TokenException("则一Token请求返回失败,返回结果为空!" + zyResponse.getMessage());
        }
        if(StringUtils.isBlank(zyResponse.getResult().getAccessToken())) {    
            throw new TokenException("则一Token请求返回数据异常,AccessToken为空!" + zyResponse.getMessage());
        }
        // 结果 zyResponse.getResult();
    }
}

返回示例

xxxxxxxxxx
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "accessToken": "64d7f367-609b-4f7d-a84d-a3d2a0b5ad85",
        "expiresIn": 602105,
        "tokenType": "bearer"
    }
}

下单

接口信息

请求方式：

post

请求地址：

• 生产：https://gw.shjiuze.cn/oms-service-api/order/add
• 测试：https://test.shjiuze.cn/oms-service-api/order/add

Headers参数

Body参数

请求示例

Java-sdk方式 下载SDK

xxxxxxxxxx
public class Sample {
    public static void main(String[] args_) {
        String appKey = "appkey";
        String appSecret = "appSecret";
        String jsonData = "下单Body参数JSON数据";
        ZYClient zyClient = new ZYClient(appKey, appSecret);
        HttpResponseData httpResponseData = 
zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/add", "accessToken", jsonData);
        if(httpResponseData == null) {    
            throw new BusinessException("则一请求失败,返回结果为空!");
         }
        if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) {   
        //重新获取token再次请求    
        httpResponseData = zyClient.doPost(Constants.TEST_HOST + 
        "/oms-service-api/order/add", "accessToken", jsonData);
        }
    }
}

返回示例

xxxxxxxxxx
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号"
    }
}

确认中标

接口信息

请求方式：

post

请求地址：

• 生产：https://gw.shjiuze.cn/oms-service-api/order/confirmBid
• 测试：https://test.shjiuze.cn/oms-service-api/order/confirmBid

Headers参数

Body参数

请求示例

Java-sdk方式 下载SDK

x
public class Sample {
    public static void main(String[] args_) {
        String appKey = "appkey";
        String appSecret = "appSecret";
        String jsonData = "确认中标Body参数JSON数据";
        ZYClient zyClient = new ZYClient(appKey, appSecret);
        HttpResponseData httpResponseData = 
zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/confirmBid", "accessToken", jsonData);
        if(httpResponseData == null) {    
            throw new BusinessException("则一请求失败,返回结果为空!");
         }
        if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) {   
        //重新获取token再次请求    
        httpResponseData = zyClient.doPost(Constants.TEST_HOST + 
        "/oms-service-api/order/confirmBid", "accessToken", jsonData);
        }
    }
}

返回示例

x
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号",
        "confirmId": "中标报价id",
        "quotePrice": "中标价格"
    }
}

确认运费接口

接口信息

概述

调用该接口确认最终运费信息。

请求方式：

post

请求地址：

• 生产：https://gw.shjiuze.cn/oms-service-api/order/confirmFreight
• 测试：https://test.shjiuze.cn/oms-service-api/order/confirmFreight

Headers参数

Body参数

请求示例

Java-sdk方式 下载SDK

x
public class Sample {
    public static void main(String[] args_) {
        String appKey = "appkey";
        String appSecret = "appSecret";
        String jsonData = "确认运费Body参数JSON数据";
        ZYClient zyClient = new ZYClient(appKey, appSecret);
        HttpResponseData httpResponseData = 
zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/confirmFreight", "accessToken", jsonData);
        if(httpResponseData == null) {    
            throw new BusinessException("则一请求失败,返回结果为空!");
         }
        if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) {   
        //重新获取token再次请求    
        httpResponseData = zyClient.doPost(Constants.TEST_HOST + 
        "/oms-service-api/order/confirmFreight", "accessToken", jsonData);
        }
    }
}

返回示例

{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号"
    }
}

取消订单

接口信息

请求方式：

post

请求地址：

• 生产：https://gw.shjiuze.cn/oms-service-api/order/cancel
• 测试：https://test.shjiuze.cn/oms-service-api/order/cancel

Headers参数

Body参数

请求示例

Java-sdk方式 下载SDK

xxxxxxxxxx
public class Sample {
    public static void main(String[] args_) {
        String appKey = "appkey";
        String appSecret = "appSecret";
        String jsonData = "取消订单Body参数JSON数据";
        ZYClient zyClient = new ZYClient(appKey, appSecret);
        HttpResponseData httpResponseData = 
zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/order/cancel", "accessToken", jsonData);
        if(httpResponseData == null) {    
            throw new BusinessException("则一请求失败,返回结果为空!");
         }
        if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) {   
        //重新获取token再次请求    
        httpResponseData = zyClient.doPost(Constants.TEST_HOST + 
        "/oms-service-api/order/cancel", "accessToken", jsonData);
        }
    }
}

返回示例

xxxxxxxxxx
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号"
    }
}

查询车辆定位

接口信息

概述

可以通过该接口查询车辆当前位置，该接口为收费接口。

请求方式：

post

请求地址：

• 生产：https://gw.shjiuze.cn/oms-service-api/vehicle/location
• 测试：https://test.shjiuze.cn/oms-service-api/vehicle/location

Headers参数

Body参数

请求示例

Java-sdk方式 下载SDK

xxxxxxxxxx
public class Sample {
    public static void main(String[] args_) {
        String appKey = "appkey";
        String appSecret = "appSecret";
        String jsonData = "车辆位置查询Body参数JSON数据";
        ZYClient zyClient = new ZYClient(appKey, appSecret);
        HttpResponseData httpResponseData = 
zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/vehicle/location", "accessToken", jsonData);
        if(httpResponseData == null) {    
            throw new BusinessException("则一请求失败,返回结果为空!");
         }
        if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) {   
        //重新获取token再次请求    
        httpResponseData = zyClient.doPost(Constants.TEST_HOST + 
        "/oms-service-api/vehicle/location", "accessToken", jsonData);
        }
    }
}

返回示例

xxxxxxxxxx
{
    "success":true,
    "businessException":false,
    "result":{
        "lng":"106.1722328011559",                  //经度
        "lat":"37.94834927106783",                  //纬度
        "speed":0,                                  //速度，km/h       
        "time":"2022-02-07 19:33:19",               //定位时间
        "address":"宁夏回族自治区吴忠市利通区清二沟,东方向,296.5米" //定位地点
    }
}

查询车辆历史轨迹

接口信息

概述

可以通过该接口查询车辆历史运行轨迹数据，该接口为收费接口。

请求方式：

post

请求地址：

• 生产：https://gw.shjiuze.cn/oms-service-api/vehicle/track
• 测试：https://test.shjiuze.cn/oms-service-api/vehicle/track

Headers参数

Body参数

请求示例

Java-sdk方式 下载SDK

xxxxxxxxxx
public class Sample {
    public static void main(String[] args_) {
        String appKey = "appkey";
        String appSecret = "appSecret";
        String jsonData = "车辆轨迹查询Body参数JSON数据";
        ZYClient zyClient = new ZYClient(appKey, appSecret);
        HttpResponseData httpResponseData = 
zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/vehicle/track", "accessToken", jsonData);
        if(httpResponseData == null) {    
            throw new BusinessException("则一请求失败,返回结果为空!");
         }
        if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) {   
        //重新获取token再次请求    
        httpResponseData = zyClient.doPost(Constants.TEST_HOST + 
        "/oms-service-api/vehicle/track", "accessToken", jsonData);
        }
    }
}

返回示例

xxxxxxxxxx
{
    "success":true,
    "businessException":false,
    "result":[
        {
            "lon":"116.6709722499687",      //经度
            "lat":"39.64092201495669",      //纬度
            "gtm":"2022-02-07 18:55:13",    //gps时间
            "spd":"249",                    //速度 除以10为km/h
            "hgt":"4",                      //海拔m
            "agl":"257"                     //正北方向夹角
        },
        {
            "lon":"116.66919560752942",
            "lat":"39.64070361333219",
            "gtm":"2022-02-07 18:55:33",
            "spd":"272",
            "hgt":"6",
            "agl":"260"
        }
    ]
}

查询订单操作记录

接口信息

概述

可以通过该接口查询订单的操作记录。

请求方式：

post

请求地址：

• 生产：https://gw.shjiuze.cn/oms-service-api/order/getOperateList
• 测试：https://test.shjiuze.cn/oms-service-api/order/getOperateList

Headers参数

Body参数

请求示例

Java-sdk方式 下载SDK

xxxxxxxxxx
public class Sample {
    public static void main(String[] args_) {
        String appKey = "appkey";
        String appSecret = "appSecret";
        String jsonData = "车辆轨迹查询Body参数JSON数据";
        ZYClient zyClient = new ZYClient(appKey, appSecret);
        HttpResponseData httpResponseData = 
zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/orderOperateRecord/getList", "accessToken", jsonData);
        if(httpResponseData == null) {    
            throw new BusinessException("则一请求失败,返回结果为空!");
         }
        if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) {   
        //重新获取token再次请求    
        httpResponseData = zyClient.doPost(Constants.TEST_HOST + 
        "/oms-service-api/orderOperateRecord/getList", "accessToken", jsonData);
        }
    }
}

返回示例

xxxxxxxxxx
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": [
        {
            "orderCode": "220101000001",
            "operateType": "ORDER_XXX",
            "operateContent": "操作详情XXXX1",
            "operateTime": "2022-02-10 18:23:30",
            "operateUser": "张三"
        },
        {
            "orderCode": "220101000001",
            "operateType": "ORDER_XXX",
            "operateContent": "操作详情XXXX2",
            "operateTime": "2022-02-08 12:43:30",
            "operateUser": "李四"
        }
    ]
}

以下接口需要对接方提供

报价接口

接口信息

概述

则一调用该接口进行报价，可以进行多次报价。

请求方式：

post

请求路径：

/quotePrice

Body参数

返回示例

x
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号"
    }
}

报价接口V2

接口信息

概述

则一调用该接口进行报价，可以进行多次报价。

请求方式：

post

请求路径：

/quotePrice

Body参数

返回示例

{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号"
    }
}

接单接口

接口信息

概述

则一调用该接口推送运单号及参考运费范围。

请求方式：

post

请求路径：

/receiveOrder

Body参数

返回示例

xxxxxxxxxx
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号"
    }
}

推送司机车辆信息

接口信息

概述

则一调用该接口推送订单司机和车辆信息，可以进行多次推送，以操作时间戳最新一次推送的司机车辆信息为准。

请求方式：

post

请求路径：

/assignVehicle

Body参数

返回示例

xxxxxxxxxx
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号"
    }
}

推送发车信息

接口信息

概述

则一调用该接口推送发车运输数据。

请求方式：

post

请求路径：

/departVehicle

Body参数

返回示例

xxxxxxxxxx
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号"
    }
}

推送到车信息

接口信息

概述

则一调用该接口推送到达数据。

请求方式：

post

请求路径：

/arriveVehicle

Body参数

返回示例

x
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号"
    }
}

推送运费信息

接口信息

概述

则一调用该接口推送最终运费信息。

请求方式：

post

请求路径：

/receiveFreight

Body参数

返回示例

x
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "客户订单号"
    }
}

Java-sdk下载

zy-java-sdk

2022-03-09更新日志

为了保证接口的通用性，本次涉及到改动的信息如下

• 下单接口：接口返回值移除子单集合，通过接单接口推送。

• 接单接口：由推送参考价改为接单接口，推送运单集合及每个运单的参考价格。

• 对接接口中子单号subCode参数命名更改为运单号waybillCode。

2023-02-22更新日志

• 增加报价接口V2版本

• 增加推送运费信息接口

• 增加确认运费接口