zeyi / open-doc

order.md 23.1 KB

[toc]

则一订单对接API

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

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">白名单

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

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">数据加签

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

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">数据加密

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

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">获取访问凭证

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">概述

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

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

post

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">请求地址：
Body参数
名称 类型 必填 示例值 描述
username String 是 zhangsan 用户名，则一提供
password String 是 password123 密码，则一提供
bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">返回参数
名称 类型 示例值 描述
success boolean true 成功标识: true 成功，false 失败
businessException boolean false 业务异常标识: true 业务异常，false 正常
errorCode String 200 错误码: 200 业务异常，500 系统异常， 空表示无错误
message String 订单号不能为空 错误信息，无错误则返回空
result ZYTokenDto accessToken结果数据
    accessToken String 000626f15b4b41bba6fe56216a5d2f73 accessToken
    expiresIn Integer 2060 有效期限单位秒，accessToken在2060秒后过期
    tokenType String bearer token类型
bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">请求示例
Http方式
POST /auth-service-api/login/password HTTP/1.1
Host:test.shjiuze.cn
Content-Type:application/json

{
  "username" : "zeyi",
  "password" : "test1111"
}
Java-sdk方式 下载SDK
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();
    }
}
bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">返回示例
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "accessToken": "64d7f367-609b-4f7d-a84d-a3d2a0b5ad85",
        "expiresIn": 602105,
        "tokenType": "bearer"
    }
}

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">下单

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">接口信息
bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">请求方式：

post

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">请求地址：
Headers参数
名称 类型 必填 示例值 描述
Authorization String 是     Bearer a2c5680001 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。
appKey String 是 0867ef5f23ef6483749e19e1692b 则一提供
timestamp String 是 1643251533306 当前时间戳毫秒值
nonce String 是 gdst9t 6位小写字母数字组合随机串
sign String 是 fa3ed338d6dfe18e7273c8692234ee70 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成
Body参数
名称 类型 必填 示例值 描述
customerOrderCode String 是     ZY230101000000001         任务编号
customerSn String 否 220101000001 客户委托单号
placeOrderTime Number 是 1643251533306 创建时间，时间戳毫秒值
loadTime Number 是 1643251533306 装货时间，时间戳毫秒值
expectArrivalTime Number 否 1643251533306 期望送达时间，时间戳毫秒值
receiptType String 否 ELECTRON_TYPE 回单类型：ELECTRON_TYPE/电子回单,PAPER_TYPE/纸质回单,NONE/无
receiptNumber Number 否 1 回单张数
receiptCode String 否 A2022012602278 回单号
payType String 否 PAY_IN_CASH 付款方式：PAY_IN_CASH/现付,PAY_ON_DELIVERY/到付,PAY_ARREARS/欠付,PAY_MONTH/月结,PAY_BACK/回付,PAY_MULTIPLE/多笔付,PAY_FREE/免费
lineName String 否 上海-天津-北京 线路名称
remark String 否 需要雨布和尾板 订单备注
loadAddress Object[] 是 装货地址信息
    stationId String 是 11212abc 园区id
    stationName String 是 高明新宜园区 园区名称
    addressId String 是 123abc 地址id
    addressName String 是 高明新宜园区-新宜6号仓-二楼18号门 装货地址名称
    lat String 是 36.221825 纬度(GPS坐标系：高德的，GCJ-02)
    lng String 是 120.632908 经度(GPS坐标系：高德的，GCJ-02)
    contactName String 否 张三 联系人
    contactMobile String 否 18801000001 联系人电话
    expectArrivalTime Number 否 1643251533306 预计到达时间，时间戳毫秒值
    expectDepartTime Number 否 1643251533306 预计发车时间，时间戳毫秒值
    sort Number 否 1 经停点顺序，如果不传则默认按数组顺序
unloadAddress Object[] 是 卸货地址信息
    stationId String 是 11212abc 园区id
    stationName String 是 高明新宜园区 园区名称
    addressId String 是 123abc 地址id
    addressName String 是 高明新宜园区-新宜6号仓-二楼18号门 卸货地址名称
    lat String 是 纬度(GPS坐标系：高德的，GCJ-02)
    lng String 是 经度(GPS坐标系：高德的，GCJ-02)
    contactName String 否 联系人
    contactMobile String 否 联系人电话
    expectArrivalTime Number 否 预计到达时间，时间戳毫秒值
    expectDepartTime Number 否 预计发车时间，时间戳毫秒值
    sort Number 否 1 经停点顺序，如果不传则默认按数组顺序
goods Object[] 否 订单货物信息
    barCode String 否 21616162626 商品条码
    skuId String 否 1223233536436 商品sku_id
    name String 是 鞋子 货物名称
    packageType String 否 包装规格
    piece Number 否 200 件数
    weight Number 否 200000 重量
    volume Number 否 50 体积
addService Object[] 否 增值服务
    serviceType String 否 服务类型
    serviceName String 是 包装服务 服务名称
    serviceDemand String 否 纸箱包装 服务要求
tags Object[] 否 订单标签
 tagName String 是 易碎物品 标签名称
demandVanType String 是 MOTOR_VAN 需求厢型：MOTOR_VAN/厢车,GAOLAN_VAN/高栏,SLAB_VAN/平板,REFRIGERATOR_CAR/冷藏,IVECO/依维柯,JINBEI/金杯,MINI_VAN/小面包,ELSE_VAN/其他
demandSpecification String 是 9.6 需求车型：2.7/3.8/4.2/6.8/7.6/9.6/11/12.5/13.5/15/16.5/17.5/19/21
demandNumber Number 否 1 为空则默认1
vehicleDemand String 否 车辆需要带雨布 车辆要求描述
vehicleCode String 否 12313 车辆编号
vehicleLicenseNum String 否 沪DP2312 车牌号
driverCode String 否 123123 司机编号
driverName String 否 张三 司机姓名
driverMobile String 否 18801733666 司机电话
bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">请求示例
Java-sdk方式 下载SDK
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/shein/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/shein/add", "accessToken", jsonData);
        }
    }
}
bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">返回示例
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "任务单号"
    }
}

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">取消订单

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">接口信息
bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">请求方式：

post

bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">请求地址：
Headers参数
名称 类型 必填 示例值 描述
Authorization String 是     Bearer a2c5680001 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。
appKey String 是 0867ef5f23ef6483749e19e1692b 则一提供
timestamp String 是 1643251533306 当前时间戳毫秒值
nonce String 是 gdst9t 6位小写字母数字组合随机串
sign String 是 fa3ed338d6dfe18e7273c8692234ee70 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成
Body参数
名称 类型 必填 示例值 描述
customerOrderCode String 是     ZY2301010001 任务单号
cancelRemark String 否 货量不足 取消原因
contact String 否 张三 联系人
contactMobile String 否 18801733666 联系电话
bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">请求示例
Java-sdk方式 下载SDK
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/shein/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/shein/cancel", "accessToken", jsonData);
        }
    }
}
bcaab557d09b45394527b6158f551cee07b824e1/order/truck/shein/order.md#">返回示例
{
    "success": true,
    "businessException": false,
    "errorCode": null,
    "message": null,
    "result": {
        "code": "则一订单号",
        "customerOrderCode": "任务单号"
    }
}

Java-sdk下载

zy-java-sdk

2023-05-06更新日志

  • [x] 增加靠站签到接口
  • [x] 增加卸车确认接口
  • [x] 增加签收接口