接口描述

Interface description
大客户直接下单接口
Interface for direct order placement of major customers
k 码未维护渠道的话统一归属位 BIGCST_STD 渠道。
All customers from the channel where a k code is not maintained should belong to the
BIGCST_STD channel.

接口地址

Interface address

测试环境

Testing environment
接 口 地 址 ： http://openuat.yto.net.cn:5002/open/oc_access_bigCustomer_adapter/v1/
cRoQ52/open18243447
Interface address:
http://openuat.yto.net.cn:5002/open/oc_access_bigCustomer_adapter/v1/cRoQ52/
open18243447
接口方法：oc_access_bigCustomer_adapter
Interface methods: oc_access_bigCustomer_adapter
接口版本：v1
Interface version: v1
测试密钥：123456
Testing secret key: 123456

传输方式

Transmission mode
本文档内描述的接口均采用 HTTPS 传输协议。客户方采用 POST 方式发送至本
接口。
All interfaces described in this document adopt the HTTPS transmission protocol. The
client should be send data to the interface by a POST request.

接口入参

Input parameters of the interface

【请求头】

[Request head]
必填 解释 示例
Header
Required Interpretation Example
租户信息必传参数
tenantId Y Tenant information, a required tenantId: PH
parameter
接受的语言及地区
Accept-Language Y Acceptable languages and Accept-Language:  en-PH
regions

本文档内描述的接口均采用 HTTPS 传输协议。客户方采用 POST 方式发送至本

接口。
All interfaces described in this document adopt the HTTPS transmission protocol. The
client should be send data to the interface by a POST request.

【请求体】

[Request body]
整体以 json 格式作为 request body 进行请求。
The request should use a request body of json format.
参数名称 必填 类型 说明
Parameter name Required Type Description
签名
sign Y String
Signature
 时间戳
timestamp Y Long
Time stamp
传递的参数，Json 格式的字符串。
param Y String Parameters to be transmitted, string of json
format.
param 格式(JSON)
format Y String
param format (JSON)

param
字节长
参数名 必填 类型 度 说明
Parameter name Required Type Byte Description
length
物流单号，唯一确定一笔快递物
流订单。
Waybill number, unique
identification for an express or
logistics order.
物流单号幂等，同一物流单号的
订单以第一次处理的信息为准，
logisticsNo Y string 100 后续请求不再处理直接返回第一
次的处理结果。
If multiple requests are sent with
the same waybill number, only the
first request will be processed. For
the subsequent requests, the result
of the first request will be returned
directly.
寄件人姓名
senderName Y string 100
Name of sender
寄件人省名称
senderProvinceName Y string 100
Province name of the sender
寄件人市名称
senderCityName Y string 100
City name of the sender
寄件人区县名称
senderCountyName N string 100
District or county name of sender
寄件人乡镇名称
senderTownName N string 200
Town name of sender
寄件人详细地址
senderAddress Y string 1000
Detailed address of sender
senderMobile Y string 45 寄件人联系电话
 Contact number of sender
收件人姓名
recipientName Y string 100
Name of receiver
收件人省名称
recipientProvinceName Y string 100
Province name of the receiver
收件人市名称
recipientCityName Y string 100
City name of receiver
收件人区县名称
recipientCountyName N string 100
District or county name of receiver
收件人乡镇名称
recipientTownName N string 200
Town name of receiver
收件人详细地址
recipientAddress Y string 1000
Detailed address of receiver
收件人联系电话
recipientMobile Y string 256
Contact number of receiver
备注，打印在面单上备注内容。
remark N string 1000 Remarks printed on the express
sheet.
物品列表
goods N Set<OrderGoods> 50
Article list
下单,总重量单位千克,三位小数
Total weight of the articles in kg
weight N BigDecimal (6,3)
and with three decimal places
0.001-100 kg
包裹长度，单位 米
packageLength N BigDecimal (5,3) Length of parcel in meter
0.001-9.999 m
包裹宽度，单位 米
packageWidth N BigDecimal (5,3) Width of parcel in meter
0.001-9.999 m
包裹高度，单位 米
packageHeight N BigDecimal (5,3) Height of parcel in meter
0.001-9.999 m
cstBusinessType N string 45 客户业务类型；
Business type of customer;
可以对客户订单进行业务或渠道
区分，定义需要和我司约定。
The customer's orders may be
classified by business or channel
and the related definitions must be
determined based on our company's
 agreement
默认为 YTO_BC。
The default value is YTO_BC.
客户的订单号；可以把交易订单
号赋值此字段，可以对应一单多
票或多单一票（自定义一个格
式）。后续有回推需求可原样回
推给客户。
Number of the customer's order;
cstOrderNo N string 100 The trade order number may be
assigned to this field and one-to-
many or many-to-one is allowed
(the format should be defined). The
field may be pushed back to the
customer if such a demand occurs
subsequently.
结算方式
Settlement method
settlementType Y Integer 2 2：月结（寄付）
2: Monthly settlement (paid by
sender)

OrderGoods
参数名称 必填 类型 长度 说明
Parameter name Required Type Length Description
物品名称
name Y string 1000
Article name
重量，单位：千克。
weight N BigDecimal (6,3)
Weight in kg.
长，单位：米
length N BigDecimal (5,3)
Length in m
宽，
width N BigDecimal (5,3)
Width
高，
height N BigDecimal (5,3)
Height
单价，
price N BigDecimal (8,2)
Unit price
数量
quantity N Integer (5,0)
Quantity
【签名规则】

[Signature rules]
签名规则及步骤如下：
The signature rules and steps are as follows:
序号 步骤
S/N Step
在 POST 时用“sign”字段进行签名验证。
1
Use the "sign" field in a POST request for signature verification.
将 param+method（方法）+v（版本）拼接得到 data，将 data 和客户密钥拼接。（通
过控制台——接口管理，添加自己所需接口，即可得到相应的测试地址、客户编
码、客户密钥、方法和版本）
2 Join param, method and v (version) to form the data and then join the data with the
customer's secret key. (Add the interface you need from the console - interface
management and you will get the testing address, customer's code and secret key and
method and version)
假设 data 内容为：opentest，partnerId（客户密钥）为 123456。 则要签名的内容为
opentest123456，然后对 opentest123456 先进行 MD5 加密，然后转换为 base64 字符
串。即经过 md5(16 位 byte)和 base64 后的内容就为 YLstCNa3x8ijQx16e/jqOA==
3 It is assumed that the data content is: Opentest and the partnerId (customer's secret key) is
123456. The content to be signed will be opentest123456. Encrypt opentest123456 with
the MD5 algorithm and then convert it into a base64 string. The final string upon md5
encryption (16 bytes) and base64 conversion will be YLstCNa3x8ijQx16e/jqOA==

签名示例

Signature example

/**
* 开放平台公共加密方法-使用 commons-codec-1.11.jar 进行 md5 加密,然后对数组进行 base64 编码
*Public encryption method of the open platform - use commons-codec-1.11.jar to complete the md5
encryption and then convert the array into a base64 string
* @param data = param+method+v
* @param secret
* @return
*/
public static String encryptSignForOpen(String data, String secret) {
String sign;
 try {
byte[] signByte = DigestUtils.md5(data + secret);
sign = Base64.encodeBase64String(signByte);
} catch (Throwable e) {
log.error("加密失败.e:{}.", e.toString());
log.error("Encryption failed.e:{}.", e.toString());
sign = "ERROR";
}
return sign;
}

接口出参

Output parameters of the interface

成功返回

Successful return data

http status 为 200 的正常接口响应
Normal interface response with a http status of 200
参数名称 必填 类型 长度 说明
Parameter name Required Type Length Description
运单号
mailNo Y string
Waybill number
三段码
Three-section address code
如果三段码计算失败，三段码为
空，不影响订单正常处理。
shortAddress N string
If the address code cannot be
calculated successfully, it will be left
empty, which will not affect the
processing of orders.

异常返回
Abnormal return
按照框架标准，http status 为 400 或 500 的返回信息，其他状态按照 http 协议规
范处理。
According to the framework standard, the return message with a http status of 400 or
500 is as follows, but the return of other status should be process following the http
protocol specification.
参数名称 必填 类型 长度 说明
Parameter name Required Type Length Description
异常编码
code Y Integer
Exceptional code
异常信息
reason Y String
Exceptional message

异常编码

Exceptional code
异常编码 异常消息支持 i18n
Exceptional code The exceptional message supports i18n
入参不合法
-40002
The input parameters are invalid
电子面单大客户拉单不可用
901010000 The query of electronic express sheet is not available for major
customers
电子面单大客户拉单业务异常:{0}
901010001 The query of electronic express sheet is exceptional for major
customers: {0}