一导通接口(API)技术文档
<h2>1 前言</h2>
<p>一导通API旨在为政务、电商、电商平台、物流工具、打单工具、仓储系统、移动APP等系统提供专业、稳定、优质的API接口服务，满足不同用户的物流管理需求。本文档就各个API接口进行详细说明，方便用户快速对接及使用一导通服务。</p>
<h2>2 接口规范说明</h2>
<h3>2.1 接口规范及说明</h3>
<h4>2.1.1 报文及报文编码</h4>
<pre><code>报文格式：Json 格式
请求方法的编码格式(utf-8)："application/x-www-form-urlencoded;charset=utf-8" 交互协议上统一用UTF-8，避免传递中文数据出现乱码。</code></pre>
<h4>2.1.2 接口数据包结构</h4>
<p>图例 -数据包结构 (系统级{数据})
<img src="https://itim-ms-sz-public-test-obs-skubucket.obs.cn-south-1.myhuaweicloud.com:443/open_file/yidaotong/62846b7b9977a_62846b7b99774.png" alt="" /></p>
<h4>2.1.3 JSON示例</h4>
<pre><code>string used="1237100";//仅作为示例ID，不可用来实际使用
//加密私钥，由一导通提供
string keyValue="56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17";//仅作为示例Key，不可用
来实际使用
//请求地址
string url="https:/api.ydt24.com/api/orderService";
//字符编码采用UTF-8
string charset="UTF-8";
//JSON字符串string
string jsonStr="{\"OrderCode\":\"\",\"ShipperCode\":\"SF\",\"LogisticCode\":\"118461988807\"}";
//把(jsonStr+APIKey)进行MD5加密，然后Base64编码，最后进行URL(utf-8)编码
datasign=HttpUtility.UrlEncode(base64(MD5(jsonStr+keyValue,"UTF-8"),"UTF-8"),Encoding.UTF8);
//请求报文参数
stringPostStr="RequestType=1002&businessID=used&RequestData=jsonStr&DataSign=datasign&DataType=DataType";
//通讯协议使用Https协议Post请求方式
string post=this.DoPost(url,PostStr);</code></pre>
<h4>2.1.4 系统级参数</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">名称</th>
<th style="text-align: left;">类型(字符长度)</th>
<th style="text-align: left;">是否必须</th>
<th style="text-align: left;">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">businessID</td>
<td style="text-align: left;">String</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">用户 ID</td>
</tr>
<tr>
<td style="text-align: left;">requestType</td>
<td style="text-align: left;">String</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">请求接口指令</td>
</tr>
<tr>
<td style="text-align: left;">dataSign</td>
<td style="text-align: left;">String</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">数据内容签名</td>
</tr>
<tr>
<td style="text-align: left;">requestData</td>
<td style="text-align: left;">String</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">请求业务参数</td>
</tr>
</tbody>
</table>
<p>快递所有接口统一使用此系统级参数，根据不同的请求接口指令接入不同的接口。</p>
<h4>2.1.5 流程示意图</h4>
<p><img src="https://itim-ms-sz-public-test-obs-skubucket.obs.cn-south-1.myhuaweicloud.com/open_file/yidaotong/62846deb3720f_62846deb37206.png" alt="" /></p>
<h3>2.2 签名说明.</h3>
<h4>2.2.1 关于签名</h4>
<p>一导通和第三方电子商务公司系统进行对接，有一定的安全机制。采用IP认证加签名的方式对接，具体方案如下：</p>
<p>1 .防止数据被篡改
在POST请求中会传递 4个必须(R)参数</p>
<pre><code>businessID==用户ID
requestType=请求指令类型
dataSign== 数据内容签名：把(请求内容(未编码)+ApiKey)进行MD5加密，然后Base64编码，最后进行URL(utf-8)编码
requestData = 请求业务参数</code></pre>
<p>注：
dataSign生成后，对方接收到数据后，以同样的算法进行签名 <strong>(</strong> 推送接口 <strong>RequestType</strong> 为<strong>101 / 102</strong> 不需要进行 <strong>URL</strong> 编码 <strong>)</strong> ，生成摘要，对比两者的摘要是否相同，如果不同，说明传递过程中发生数据篡改。</p>
<p>2 .调用接口的身份认证
注册成为一导通用户后，会生成对应的用户ID和APIKey，用户ID相当于用户名，APIKey相当于密码。举例：</p>
<p>1 .假设</p>
<pre><code>requestData (JSON)内容为：
{'OrderCode':'','ShipperCode':'SF','LogisticCode':'118954907573'}
经过 URL(UTF-8)编码的内容为：%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27SF%27%2c%27LogisticCode%27%3a%27118954907573%27%7d；
businessID=1237100【示例 ID，不可用来实际使用】
APIKey=56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17【示例 Key，不可用来实际使用】</code></pre>
<p>2 .那么DataSign签名的内容为</p>
<pre><code>1. 那么 DataSign 签名的内容为{'OrderCode':'','ShipperCode':'SF','LogisticCode':'118954907573'}56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17
经过 md5 和 base64 后的内容就为：
OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=，
在经过 URL(UTF-8)编码的内容为：
OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE%3d
最终要发送的数据为：
RequestType=1002&EBusinessID=1237100&RequestData=%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27SF%27%2c%27LogisticCode%27%3a%27118954907573%27%7d&DataSign=OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE%3d&DataType=2</code></pre>
<p>3 .接收方收到数据后，获得</p>
<pre><code>businessID和requestData和dataSign等这几个数据。 </code></pre>
<p>4 .接收方对 businessID 得到 APIKey，requestData+APIKey 的数据进行md5 和 base64 后的内容就为</p>
<pre><code>OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=</code></pre>
<p>5 .接收方判断签名后的数据跟传递过来的 DataSign 是否一致，如果一致进行业务操作，如果不一致返回错误。</p>
<h4>2.2.2 (Java)DataSign签名加密代码.</h4>
<pre><code class="language-java">import com.sun.org.apache.xerces.internal.impl.dv.util.Base64;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.security.MessageDigest;
import java.util.HashMap;
import java.util.Map;
/**
* @author: chenjunqin
* @date: 2022/5/10 16:02
*/
public class YiDaoTongSignDemo {
public static void main(String[] args) throws Exception {
// 组装应用级参数
String requestData = "{" +
"'OrderCode':''," +
"'ShipperCode':'SF'," +
"'LogisticCode':'118954907573'" +
"}";
String businessId = "1237100";
String apiKey = "56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17";
String requestType = "1002";
// 组装系统级参数
Map<String, String> params = new HashMap<>();
params.put("requestData", urlEncoder(requestData, "UTF-8"));
// RequestData: %7B%27OrderCode%27%3A%27%27%2C%27ShipperCode%27%3A%27SF%27%2C%27LogisticCode%27%3A%27118954907573%27%7D
params.put("businessId", businessId);
params.put("requestType", requestType);
String dataSign = encrypt(requestData, apiKey, "UTF-8");
// dataSign: OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=
params.put("dataSign", urlEncoder(dataSign, "UTF-8"));
// DataSign: OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE%3D
params.put("dataType", "2");
System.out.println(params);
}
private static String urlEncoder(String str, String charset) throws UnsupportedEncodingException {
return URLEncoder.encode(str, charset);
}
private static String encrypt(String content, String keyValue, String charset) throws Exception {
return base64(MD5(content + keyValue, charset), charset);
}
/**
* MD5加密
* str 内容
* charset 编码方式
*
* @throws Exception
*/
@SuppressWarnings("unused")
private static String MD5(String str, String charset) throws Exception {
MessageDigest md = MessageDigest.getInstance("MD5");
md.update(str.getBytes(charset));
byte[] result = md.digest();
StringBuffer sb = new StringBuffer(32);
for (int i = 0; i < result.length; i++) {
int val = result[i] & 0xff;
if (val <= 0xf) {
sb.append("0");
}
sb.append(Integer.toHexString(val));
}
return sb.toString().toLowerCase();
}
/**
* base64编码
* str 内容
* charset 编码方式
*
* @throws UnsupportedEncodingException
*/
private static String base64(String str, String charset) throws UnsupportedEncodingException {
return Base64.encode(str.getBytes(charset));
}
}</code></pre>
<h3>2.3 接入步骤</h3>
<p><strong>1. 一导通官网注册账号成为一导通用户 ;</strong>
一导通提供的用户ID是调用接口服务的身份证明，不可更改、不可转用，APIKey是应用访问API的签名附加密钥，必须妥善保存。两者关系类似于用户名和密码，两者都会在签名和业务参数中使用。</p>
<pre><code>官网登录网址：
https://web.ydaotong.com/
官网接口介绍网址：
https://web.ydaotong.com/api/</code></pre>
<p><strong>2.登陆用户后台，进行实名认证，并开通会员服务;</strong></p>
<p><strong>3.根据技术文档进行开发并在调试平台测试联调；</strong></p>
<p><strong>4. 系统发布上线。</strong>
注意：测试环境中获取的测试快递单号不可用于实际发货。</p>
<h2>3 API接口</h2>
<h3>3.1 下单接口</h3>
<h4>3.1.1 功能说明</h4>
<ol>
<li>此接口用于向快递/快运公司下发订单并获取快递单号。</li>
</ol>
<h4>3.1.2 基本信息</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">接口指令</th>
<th style="text-align: left;"><strong>1001</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">请求方式</td>
<td style="text-align: left;">POST 请求</td>
</tr>
<tr>
<td style="text-align: left;">支持格式</td>
<td style="text-align: left;">只支持 Json 格式、UTF-8 编码</td>
</tr>
<tr>
<td style="text-align: left;">批量请求</td>
<td style="text-align: left;">不支持，并发不超过 20 次/S</td>
</tr>
<tr>
<td style="text-align: left;">接口地址</td>
<td style="text-align: left;">测试地址：https:/sit-api.ydt24.com/api/orderService 正式地址：https:/api.ydt24.com/api/orderService</td>
</tr>
</tbody>
</table>
<h4>3.1.3 接口规则</h4>
<p>1. 请求报文中不允许出现以下特殊字符： ' " # & + < > % \
2. 接口实时返回快递/快运单号。
3. 订单编号 orderCode由用户自定义，不可重复；重复订单号下单，系统会 106 状态报错并返回第一次请求的结果。
4. 如因用户原因(如：恶意下单、批量下单长时间不发货等)导致快递公司投诉，一导通将停用用户接口权限</p>
<h4>3.1.4 支持情况</h4>
<ol>
<li>接入快递公司：顺丰速运、EMS。</li>
</ol>
<h4>3.1.5 应用场景</h4>
<p>电商平台、打单工具、ERP系统、WEB端、APP移动端、小程序</p>
<h4>3.1.6 应用级参数</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">名称</th>
<th style="text-align: left;">类型(字符长度)</th>
<th style="text-align: left;">是否必须</th>
<th style="text-align: left;">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">shipperCode</td>
<td style="text-align: left;">String(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">快递公司编码</td>
</tr>
<tr>
<td style="text-align: left;">orderCode</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">订单编号(自定义，不可重复)</td>
</tr>
<tr>
<td style="text-align: left;">payType</td>
<td style="text-align: left;">Int(1)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">运费支付方式：1-现付，2-到付</td>
</tr>
<tr>
<td style="text-align: left;">expType</td>
<td style="text-align: left;">String(2)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">详细快递类型参考《快递业务类型.xlsx》</td>
</tr>
<tr>
<td style="text-align: left;">receiver.company</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">收件人公司</td>
</tr>
<tr>
<td style="text-align: left;">receiver.name</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">收件人</td>
</tr>
<tr>
<td style="text-align: left;">receiver.mobile</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">手机号码</td>
</tr>
<tr>
<td style="text-align: left;">receiver.postCode</td>
<td style="text-align: left;">String(10)</td>
<td style="text-align: left;">可选</td>
<td style="text-align: left;">收件地邮编(shipperCode 为EMS时必填)</td>
</tr>
<tr>
<td style="text-align: left;">receiver.province</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">收件省(如广东省，不要缺少“省”；如是直辖市，请直接传北京、上海等；如是自治区，请直接传广西壮族自治区等)</td>
</tr>
<tr>
<td style="text-align: left;">receiver.city</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">收件市(如深圳市，不要缺少“市；如是市辖区，请直接传北京市、上海市等”)</td>
</tr>
<tr>
<td style="text-align: left;">receiver.county</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">收件区/县(如福田区，不要缺少“区”或“县”)</td>
</tr>
<tr>
<td style="text-align: left;">receiver.address</td>
<td style="text-align: left;">String(100)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">收件人详细地址(不用传省市区)</td>
</tr>
<tr>
<td style="text-align: left;">sender.company</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">发件人公司</td>
</tr>
<tr>
<td style="text-align: left;">sender.name</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">发件人</td>
</tr>
<tr>
<td style="text-align: left;">sender.tel</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">电话与手机，必填一个</td>
</tr>
<tr>
<td style="text-align: left;">sender.mobile</td>
<td style="text-align: left;">String(20)</td>
</tr>
<tr>
<td style="text-align: left;">sender.postCode</td>
<td style="text-align: left;">String(10)</td>
<td style="text-align: left;">可选</td>
<td style="text-align: left;">发件地邮编(shipperCode 为EMS时必填)</td>
</tr>
<tr>
<td style="text-align: left;">sender.province</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">发件省(如广东省，不要缺少“省”； 如是直辖市，请直接传北京、上海等；如是自治区，请直接传广西壮族自治区等)</td>
</tr>
<tr>
<td style="text-align: left;">sender.city</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">发件市(如深圳市，不要缺少“市；如是市辖区，请直接传北京市、上海市等”)</td>
</tr>
<tr>
<td style="text-align: left;">sender.county</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">发件区/县(如福田区，不要缺少“区”或“县”)</td>
</tr>
<tr>
<td style="text-align: left;">sender.address</td>
<td style="text-align: left;">String(100)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">发件人详细地址(不用传省市区)</td>
</tr>
<tr>
<td style="text-align: left;">isNotice</td>
<td style="text-align: left;">Int(1)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">是否通知快递员上门揽件0-通知，1-不通知，不填则默认为 1</td>
</tr>
<tr>
<td style="text-align: left;">startDate</td>
<td style="text-align: left;">String(32)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">上门揽件开始时间，示例：2021-01-01 09:00:00</td>
</tr>
<tr>
<td style="text-align: left;">endDate</td>
<td style="text-align: left;">String(32)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">上门揽件结束时间，示例：2021-01-01 17:00:00</td>
</tr>
<tr>
<td style="text-align: left;">weight</td>
<td style="text-align: left;">Double(10,3)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">包裹总重量 kg</td>
</tr>
<tr>
<td style="text-align: left;">quantity</td>
<td style="text-align: left;">Int(2)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">包裹数(最多支持 300 件)一个包裹对应一个运单号，如果是大于 1 个包裹，返回则按照子母件的方式返回母运单号和子运单号</td>
</tr>
<tr>
<td style="text-align: left;">volume</td>
<td style="text-align: left;">Double(20,3)</td>
<td style="text-align: left;">可选</td>
<td style="text-align: left;">包裹总体积 m3</td>
</tr>
<tr>
<td style="text-align: left;">remark</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">备注</td>
</tr>
<tr>
<td style="text-align: left;">commodity.goodsName</td>
<td style="text-align: left;">String(100)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">商品名称</td>
</tr>
<tr>
<td style="text-align: left;">commodity.goodsCode</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">商品编码</td>
</tr>
<tr>
<td style="text-align: left;">commodity.goodsquantity</td>
<td style="text-align: left;">Int(5)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">商品件数</td>
</tr>
<tr>
<td style="text-align: left;">commodity.goodsPrice</td>
<td style="text-align: left;">Double(10)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">商品价格（当 ShipperCode 为BETWL 时必填）</td>
</tr>
<tr>
<td style="text-align: left;">commodity.goodsWeight</td>
<td style="text-align: left;">Double(10,3)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">商品重量 kg</td>
</tr>
<tr>
<td style="text-align: left;">commodity.goodsDesc</td>
<td style="text-align: left;">String(50)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">商品描述</td>
</tr>
<tr>
<td style="text-align: left;">commodity.goodsVol</td>
<td style="text-align: left;">Double(15,3)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">商品体积 m3</td>
</tr>
<tr>
<td style="text-align: left;">isSubscribe</td>
<td style="text-align: left;">String(1)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">是否订阅轨迹推送0-不订阅，1-订阅，不填默认为0</td>
</tr>
</tbody>
</table>
<p><strong>请求示例 :</strong></p>
<pre><code>{
"OrderCode": "012657018199",
"ShipperCode": "SF",
"PayType": 1,
"MonthCode": "1234567890",
"ExpType": 1,
"Cost": 1.0,
"OtherCost": 1.0,
"Sender": {
"Company": "LV",
"Name": "一导通",
"Mobile": "15018442396",
"ProvinceName": "上海",
"CityName": "上海市",
"ExpAreaName": "青浦区",
"Address":"明珠路"
},
"Receiver": {
"Company": "GCCUI",
"Name": "Yann",
"Mobile": "15018442396",
"ProvinceName": "北京",
"CityName": "北京市",
"ExpAreaName": "朝阳区",
"Address": "三里屯街道"
},
"Commodity": [
{"GoodsName": "鞋子",
"Goodsquantity": 1,
"GoodsWeight": 1.0
}
],
"AddService": [
{
"Name": "COD",
"Value": "1020",
"CustomerID": "1234567890"
}
],
"Weight": 1.0,
"Quantity": 1,
"Volume": 0.0,
"Remark": "小心轻放"
}</code></pre>
<h4>3.1.7 返回参数</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">名称</th>
<th style="text-align: left;">类型(字符长度)</th>
<th style="text-align: left;">是否必须</th>
<th style="text-align: left;">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">businessId</td>
<td style="text-align: left;">String(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">用户 ID</td>
</tr>
<tr>
<td style="text-align: left;">success</td>
<td style="text-align: left;">Bool(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">成功与否(true/false)</td>
</tr>
<tr>
<td style="text-align: left;">errorCode</td>
<td style="text-align: left;">String(5)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">失败编码</td>
</tr>
<tr>
<td style="text-align: left;">errorMessage</td>
<td style="text-align: left;">String(50)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">失败原因</td>
</tr>
<tr>
<td style="text-align: left;">data</td>
<td style="text-align: left;">obj</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">返回结果</td>
</tr>
</tbody>
</table>
<p>data对象</p>
<table>
<thead>
<tr>
<th style="text-align: left;">名称</th>
<th style="text-align: left;">类型(字符长度)</th>
<th style="text-align: left;">是否必须</th>
<th style="text-align: left;">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">orderCode</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">订单编号</td>
</tr>
<tr>
<td style="text-align: left;">shipperCode</td>
<td style="text-align: left;">String(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">快递公司编码</td>
</tr>
<tr>
<td style="text-align: left;">logisticsCode</td>
<td style="text-align: left;">String(400)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">快递单号</td>
</tr>
<tr>
<td style="text-align: left;">markDestination</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">大头笔</td>
</tr>
<tr>
<td style="text-align: left;">signWaybillCode</td>
<td style="text-align: left;">String(15)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">签回单单号</td>
</tr>
<tr>
<td style="text-align: left;">originCode</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">始发地区域编码</td>
</tr>
<tr>
<td style="text-align: left;">originName</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">始发地/始发网点</td>
</tr>
<tr>
<td style="text-align: left;">destinatioCode</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">目的地区域编码</td>
</tr>
<tr>
<td style="text-align: left;">destinatioName</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">目的地/到达网点</td>
</tr>
<tr>
<td style="text-align: left;">sortingCode</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">分拣编码</td>
</tr>
<tr>
<td style="text-align: left;">packageCode</td>
<td style="text-align: left;">String(20)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">集包编码</td>
</tr>
<tr>
<td style="text-align: left;">packageName</td>
<td style="text-align: left;">String(50)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">集包地</td>
</tr>
<tr>
<td style="text-align: left;">destinationAllocationCentre</td>
<td style="text-align: left;">String(50)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">目的地分拨</td>
</tr>
<tr>
<td style="text-align: left;">subCount</td>
<td style="text-align: left;">Int(5)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">子单数量</td>
</tr>
<tr>
<td style="text-align: left;">subOrders</td>
<td style="text-align: left;">String(400)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">子单单号（数组形式）</td>
</tr>
</tbody>
</table>
<p>返回示例</p>
<p>失败：</p>
<pre><code>{
"businessId":"123456",
"resultCode":"106",
"reason":" 该 订 单 号 已 下 单 成 功 ",
"uniquerRequestNumber":"5e66486b-8fbc-4131-b875-9b13d2ad1354"
} </code></pre>
<p>成功：</p>
<pre><code>{
"businessID":"1237100",
"order":{
"orderCode":"012657700387",
"shipperCode":"SF",
"logisticCode":"50002498503427",
"markDestination":"京-朝阳(京-1)",
"originCode":"200000",
"originName":"上海分拨中心",
"packageCode":"北京"
},
"success":true,
"resultCode":"100",
"reason":"成功"
} </code></pre>
<h3>3.2 下单取消接口</h3>
<h4>3.2.1 功能说明</h4>
<p>此接口用于取消“下单接口”下单成功的订单，回收快递单号。</p>
<h4>3.2.2 基本信息</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">接口指令</th>
<th style="text-align: left;">1002</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">批量请求</td>
<td style="text-align: left;">不支持</td>
</tr>
<tr>
<td style="text-align: left;">接口地址</td>
<td style="text-align: left;"><p>测试地址：https:/sit-api.ydt24.com/api/open/cancelOrder</p><p>正式地址：https:/api.ydt24.com/api/open/cancelOrder</p></td>
</tr>
</tbody>
</table>
<h4>3.2.3 接口规则</h4>
<p>只支持取消通过下单接口下单成功的订单；</p>
<p>只支持取消未揽件的订单；</p>
<p>订单取消后，订单号仍不可重复使用；</p>
<p>订单取消后快递单号的回收规则以快递公司为准。</p>
<h4>3.2.4支持情况</h4>
<p>支持快递公司：顺丰速运、EMS</p>
<h4>3.2.5应用级参数</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">名称</th>
<th style="text-align: left;">类型(字符长度)</th>
<th style="text-align: left;">是否必须</th>
<th style="text-align: left;">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">shipperCode</td>
<td style="text-align: left;">String(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">快递公司编码</td>
</tr>
<tr>
<td style="text-align: left;">orderCode</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">订单编号</td>
</tr>
<tr>
<td style="text-align: left;">logisticsCode</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">快递单号</td>
</tr>
</tbody>
</table>
<p>请求示例:</p>
<pre><code class="language-json">{
"shipperCode":"SF",
"orderCode":"TEST201209211045",
"expNo":"900008664480"
} </code></pre>
<h4>3.2.6返回参数</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">名称</th>
<th style="text-align: left;">类型(字符长度)</th>
<th style="text-align: left;">是否必须</th>
<th style="text-align: left;">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">businessId</td>
<td style="text-align: left;">String(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">用户 ID</td>
</tr>
<tr>
<td style="text-align: left;">success</td>
<td style="text-align: left;">Bool(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">成功与否(true/false)</td>
</tr>
<tr>
<td style="text-align: left;">resultCode</td>
<td style="text-align: left;">String(5)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;"><a href="#_bookmark97">返回编码</a></td>
</tr>
<tr>
<td style="text-align: left;">reason</td>
<td style="text-align: left;">String(50)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">失败原因</td>
</tr>
</tbody>
</table>
<p>返回示例:</p>
<pre><code class="language-json">{
"businessID": "1237100",
"success": true, "resultCode": "100"
} </code></pre>
<h3>3.3 路由查询接口</h3>
<h4>3.3.1功能说明</h4>
<p>此接口用于向快递公司实时查询物流轨迹信息。</p>
<h4>3.3.2 基本信息</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">接口指令</th>
<th style="text-align: left;">2001</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">支持格式</td>
<td style="text-align: left;">Json 格式</td>
</tr>
<tr>
<td style="text-align: left;">批量请求</td>
<td style="text-align: left;">不支持，并发不超过 10 次/S</td>
</tr>
<tr>
<td style="text-align: left;">接口地址</td>
<td style="text-align: left;"><p>测试地址：https:/sit-api.ydt24.com/api/orderService</p><p>正式地址：https:/api.ydt24.com/api/orderService</p></td>
</tr>
</tbody>
</table>
<h4>3.3.3 接口规则</h4>
<p>返回的物流轨迹信息按照发生时间的升序排列。</p>
<h4>3.3.4 支持情况</h4>
<p>支持快递公司：顺丰速运、EMS</p>
<h4>3.3.5 应用级参数</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">名称</th>
<th style="text-align: left;">类型(字符长度)</th>
<th style="text-align: left;">是否必须</th>
<th style="text-align: left;">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">shipperCode</td>
<td style="text-align: left;">String(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">快递公司编码</td>
</tr>
<tr>
<td style="text-align: left;">logisticCode</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">快递单号</td>
</tr>
</tbody>
</table>
<p>请求示例：</p>
<pre><code class="language-json">SF 请求示例：{OrderCode": "", "CustomerName": "1234", "ShipperCode": "SF", "LogisticCode": "SF00003618100"}</code></pre>
<h4>3.3.6 返回参数</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">名称</th>
<th style="text-align: left;">类型(字符长度)</th>
<th style="text-align: left;">是否必须</th>
<th style="text-align: left;">描述</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">businessID</td>
<td style="text-align: left;">String(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">用户 ID</td>
</tr>
<tr>
<td style="text-align: left;">orderCode</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">订单编号</td>
</tr>
<tr>
<td style="text-align: left;">shipperCode</td>
<td style="text-align: left;">String(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">快递公司编码</td>
</tr>
<tr>
<td style="text-align: left;">logisticCode</td>
<td style="text-align: left;">String(30)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">快递单号</td>
</tr>
<tr>
<td style="text-align: left;">success</td>
<td style="text-align: left;">Bool(10)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">成功与否(true/false)</td>
</tr>
<tr>
<td style="text-align: left;">reason</td>
<td style="text-align: left;">String(50)</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">失败原因</td>
</tr>
<tr>
<td style="text-align: left;">state</td>
<td style="text-align: left;">String(5)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">普通物流状态： 0-暂无轨迹信息已揽收在途中签收问题件</td>
</tr>
<tr>
<td style="text-align: left;">traces.acceptTime</td>
<td style="text-align: left;">String(32)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">轨迹发生时间,示例：2021-01-01 09:00:00</td>
</tr>
<tr>
<td style="text-align: left;">traces.acceptStation</td>
<td style="text-align: left;">String(500)</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">轨迹描述</td>
</tr>
</tbody>
</table>