快递拦截
<p>[TOC]</p>
<h3>简介</h3>
<ul>
<li>拦截已在途中的物流单号</li>
<li>仅支持在途中拦截，如货物未发出或派送中、已签收，则无法通过该接口进行拦截</li>
<li>仅支持拦截商家自己下的单，拦截时需要提供下单账号、密钥等参数，下文详述</li>
<li>支持物流：极兔、德邦、顺丰、申通、中通、邮政、京东、韵达</li>
</ul>
<h3>接口调用说明</h3>
<h4>请求方式</h4>
<p>如接口没有单独说明，所有接口均为：<strong>POST</strong></p>
<h4>请求参数</h4>
<p>请求参数包括公共参数和业务参数（业务参数见具体接口说明）
如果请求格式为 application/form-data或application/x-www-form-urlencoded的，需要把<strong>公共参数</strong>和<strong>业务参数</strong>一并放在<strong>请求参数</strong>中提交
如果请求格式为application/json的，需要把<strong>公共参数</strong>放在<strong>请求Header</strong>中提交</p>
<p><a name="公共请求参数"></a></p>
<h5>公共请求参数</h5>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>appId</td>
<td>String</td>
<td>是</td>
<td>服务商分配的唯一标识</td>
</tr>
<tr>
<td>timestamp</td>
<td>Long</td>
<td>是</td>
<td>当前时间戳（毫秒）</td>
</tr>
<tr>
<td>sign</td>
<td>String</td>
<td>是</td>
<td>签名，详见签名算法说明</td>
</tr>
</tbody>
</table>
<h5>签名算法说明</h5>
<pre><code>sign = sha256(appId + appSecret + timestamp)</code></pre>
<p>用服务商分配的 <strong>appId</strong>、服务商分配的 <strong>appSecret</strong>，当前时间戳（毫秒） <strong>timestamp</strong>，按上述顺序拼接成字符串，再进行 <strong>sha256</strong> 哈希得到。如下：</p>
<pre><code class="language-java">String appId = &quot;xyzxy2121zxyz&quot;；
String timestamp = &quot;1555378976238&quot;；
String appSecret = &quot;efcefcef1121cefcefc1212121&quot;；
String str = appId + appSecret + timestamp；
String sign = sha256(str)；</code></pre>
<h4>返回说明</h4>
<h5>公共返回字段说明</h5>
<p>所有接口均返回以下公共字段：</p>
<table>
<thead>
<tr>
<th>字段名</th>
<th><div style="width:430px">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>code</td>
<td>返回码，详见：code返回码说明</td>
</tr>
<tr>
<td>msg</td>
<td>code对应的描述</td>
</tr>
<tr>
<td>charge</td>
<td>计费标志 true为计费，false为不计费</td>
</tr>
<tr>
<td>taskNo</td>
<td>本次请求号</td>
</tr>
<tr>
<td>data</td>
<td>返回具体结果，object类型，详见data返回字段描述</td>
</tr>
</tbody>
</table>
<p><a name="code返回码说明"></a></p>
<table>
<thead>
<tr>
<th>code</th>
<th><div style="width:430px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>成功</td>
</tr>
<tr>
<td>301</td>
<td>重复请求，物流拦截中</td>
</tr>
<tr>
<td>400</td>
<td>参数错误</td>
</tr>
<tr>
<td>404</td>
<td>接口地址不正确</td>
</tr>
<tr>
<td>500</td>
<td>系统维护，请稍候再试</td>
</tr>
<tr>
<td>601</td>
<td>接口未开通</td>
</tr>
<tr>
<td>602</td>
<td>账号停用</td>
</tr>
<tr>
<td>604</td>
<td>接口停用</td>
</tr>
<tr>
<td>606</td>
<td>调用超限，请稍候再试</td>
</tr>
<tr>
<td>607</td>
<td>ip不在白名单</td>
</tr>
<tr>
<td>609</td>
<td>请求过于频繁，请稍候再试</td>
</tr>
<tr>
<td>610</td>
<td>请求超时</td>
</tr>
<tr>
<td>999</td>
<td>其他，以实际返回为准</td>
</tr>
</tbody>
</table>
<hr />
<h3>发起拦截</h3>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/express-intercept/request</code></p>
<h4>请求格式</h4>
<ul>
<li>application/form-data</li>
</ul>
<h4>业务参数</h4>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>shipperCode</td>
<td>String</td>
<td>是</td>
<td>快递公司编码，详见快递公司编码</td>
</tr>
<tr>
<td>logisticCode</td>
<td>String</td>
<td>是</td>
<td>运单号</td>
</tr>
<tr>
<td>operationType</td>
<td>String</td>
<td>是</td>
<td>拦截操作类型：<br>1-返回寄件网点<br>2-原址返回<br>4-转寄<br>圆通、极兔、德邦只支持类型2</td>
</tr>
<tr>
<td>remark</td>
<td>String</td>
<td>是</td>
<td>拦截备注说明</td>
</tr>
<tr>
<td>source</td>
<td>String</td>
<td>否</td>
<td>拦截方式</td>
</tr>
<tr>
<td>customerCode</td>
<td>String</td>
<td>条件是</td>
<td>客户编码</td>
</tr>
<tr>
<td>customerName</td>
<td>String</td>
<td>条件是</td>
<td>客户名称</td>
</tr>
<tr>
<td>customerPsw</td>
<td>String</td>
<td>条件是</td>
<td>客户密钥</td>
</tr>
<tr>
<td>customerPhone</td>
<td>String</td>
<td>条件是</td>
<td>手机号</td>
</tr>
<tr>
<td>customerSiteCode</td>
<td>String</td>
<td>条件是</td>
<td>网点编号</td>
</tr>
<tr>
<td>receiveUsername</td>
<td>String</td>
<td>条件是</td>
<td>新收件人</td>
</tr>
<tr>
<td>receivePhone</td>
<td>String</td>
<td>条件是</td>
<td>新收件电话</td>
</tr>
<tr>
<td>receiveProvince</td>
<td>String</td>
<td>条件是</td>
<td>新收件省</td>
</tr>
<tr>
<td>receiveCity</td>
<td>String</td>
<td>条件是</td>
<td>新收件市</td>
</tr>
<tr>
<td>receiveArea</td>
<td>String</td>
<td>条件是</td>
<td>新收件区</td>
</tr>
<tr>
<td>receiveAddress</td>
<td>String</td>
<td>条件是</td>
<td>新收件街道地址</td>
</tr>
</tbody>
</table>
<ul>
<li>operationType=4时，receiveUsername, receivePhone, receiveProvince, receiveCity, receiveArea, receiveAddress必须</li>
</ul>
<h4>快递公司和参数对照</h4>
<table>
<thead>
<tr>
<th>快递公司</th>
<th>CustomerCode</th>
<th>customerPsw</th>
<th>customerPhone</th>
<th>customerSiteCode</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>中通快递</td>
<td>客户编码</td>
<td>密钥</td>
<td></td>
<td>网点编号</td>
<td>可联系合作网点提供<br>月结账号、秘钥，不同网点的单号，首次使用时需要把客户编码、客户秘钥、网点编号 提供服务商绑定</td>
</tr>
<tr>
<td><del>圆通速递</del></td>
<td><del>月结账号</del></td>
<td><del>密钥</del></td>
<td></td>
<td></td>
<td><del>圆通暂不可用</del></td>
</tr>
<tr>
<td>极兔速递</td>
<td>极兔开放平台应用<br>apiAccount</td>
<td>极兔开放平台应用<br>privateKey</td>
<td></td>
<td></td>
<td>用户侧在极兔开放平台注册的开发账号，<br>完成企业认证和应用创建后，<br>获取apiAccount和privateKey</td>
</tr>
<tr>
<td>德邦快递</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td>不需要鉴权</td>
</tr>
<tr>
<td>顺丰速运</td>
<td></td>
<td></td>
<td>原单寄件人或收件人<br>手机后四位</td>
<td></td>
<td></td>
</tr>
<tr>
<td>京东快递/快运）</td>
<td>客户编码/青龙编码</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>申通</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td>不需要鉴权，<br>参数source=2</td>
</tr>
<tr>
<td>韵达</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td>不需要鉴权，<br>参数source=2</td>
</tr>
<tr>
<td>邮政</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td>不需要鉴权，<br>参数source=2</td>
</tr>
</tbody>
</table>
<ul>
<li>极兔速递：用户侧在<a href="https://open.jtexpress.com.cn/#/control/personalCenter"><strong>极兔开放平台</strong></a>注册开发账号，完成<strong>企业认证</strong>和<strong>应用创建</strong>后，获得apiAccount和privateKey </li>
</ul>
<h4>支持快递公司情况</h4>
<table>
<thead>
<tr>
<th>快递公司</th>
<th>原址返回</th>
<th>返回寄件地址</th>
<th>转寄</th>
<th>取消拦截</th>
<th>单号来源限制</th>
</tr>
</thead>
<tbody>
<tr>
<td>中通</td>
<td>支持</td>
<td>支持</td>
<td>支持</td>
<td>支持</td>
<td>不限制单号来源</td>
</tr>
<tr>
<td>极兔</td>
<td>支持</td>
<td>不限制单号来源</td>
</tr>
<tr>
<td>顺丰</td>
<td>支持</td>
<td>支持</td>
<td>不限制单号来源</td>
</tr>
<tr>
<td>德邦</td>
<td>支持</td>
<td>不限制单号来源</td>
</tr>
<tr>
<td>京东</td>
<td>支持</td>
<td>支持</td>
<td>不限制单号来源</td>
</tr>
<tr>
<td>邮政</td>
<td>支持</td>
<td>支持</td>
<td>只支持拦截淘系单</td>
</tr>
<tr>
<td>申通</td>
<td>支持</td>
<td>支持</td>
<td>不限制单号来源</td>
</tr>
<tr>
<td>韵达</td>
<td>支持</td>
<td>支持</td>
<td>不限制单号来源</td>
</tr>
<tr>
<td><del>圆通</del></td>
<td><del>支持</del></td>
<td><del>只支持拦截淘系单</del></td>
</tr>
</tbody>
</table>
<h4>成功返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200,// 返回码，详见返回码说明
&quot;msg&quot;: &quot;成功&quot;,// 返回码对应描述
&quot;taskNo&quot;: &quot;043439882226367117195632&quot;,// 本次请求号
&quot;charge&quot;: true, // 计费标志
}</code></pre>
<h4>失败返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 400,
&quot;charge&quot;: false,
&quot;msg&quot;: &quot;快递公司编号不能为空&quot;
}</code></pre>
<hr />
<h3>查询拦截结果</h3>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/express-intercept/query</code></p>
<h4>业务参数</h4>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>shipperCode</td>
<td>String</td>
<td>是</td>
<td>快递公司编码，详见快递公司编码</td>
</tr>
<tr>
<td>logisticCode</td>
<td>String</td>
<td>是</td>
<td>快递单号</td>
</tr>
</tbody>
</table>
<h4>请求格式</h4>
<ul>
<li>application/form-data</li>
</ul>
<h4>成功返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200, // 返回码，详见返回码说明
&quot;msg&quot;: &quot;成功&quot;, // 返回码对应描述
&quot;taskNo&quot;: &quot;448290834186092138576138&quot;, // 本次请求号
&quot;charge&quot;: false, //查询接口不计费
&quot;data&quot;: {
&quot;InterceptStatus&quot;: &quot;105&quot;, // 拦截状态，详见拦截状态说明
&quot;InterceptStatusName&quot;: &quot;拦截成功&quot;, // 拦截状态说明
&quot;LogisticCode&quot;: &quot;73100096766607&quot;, // 快递单号
&quot;ShipperCode&quot;: &quot;ZTO&quot;, // 快递公司编码
&quot;Receiver&quot;: { // 收件信息
&quot;ProvinceName&quot;: &quot;浙江省&quot;,
&quot;CityName&quot;: &quot;杭州市&quot;,
&quot;ExpareaName&quot;: &quot;余杭区&quot;,
&quot;Address&quot;: &quot;&quot;,
&quot;Name&quot;: &quot;爱力中心&quot;,
&quot;Mobile&quot;: &quot;15900000000&quot;
}
}
}
</code></pre>
<h4>失败返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 400,
&quot;msg&quot;: &quot;快递单号不能为空&quot;,
&quot;charge&quot;: false
}</code></pre>
<h3>附录</h3>
<h4>快递公司编号</h4>
<table>
<thead>
<tr>
<th>快递公司</th>
<th>编码</th>
</tr>
</thead>
<tbody>
<tr>
<td>中通快递</td>
<td>ZTO</td>
</tr>
<tr>
<td>圆通速递</td>
<td>YTO</td>
</tr>
<tr>
<td>极兔速递</td>
<td>JTSD</td>
</tr>
<tr>
<td>德邦快递</td>
<td>DBL</td>
</tr>
<tr>
<td>顺丰速运</td>
<td>SF</td>
</tr>
<tr>
<td>京东快递/快运</td>
<td>JD</td>
</tr>
<tr>
<td>申通</td>
<td>STO</td>
</tr>
<tr>
<td>韵达</td>
<td>YD</td>
</tr>
<tr>
<td>邮政</td>
<td>EMS</td>
</tr>
</tbody>
</table>
<h4>拦截状态说明</h4>
<table>
<thead>
<tr>
<th>InterceptStatus</th>
<th>状态</th>
</tr>
</thead>
<tbody>
<tr>
<td>101</td>
<td>已登记</td>
</tr>
<tr>
<td>102</td>
<td>拦截中</td>
</tr>
<tr>
<td>103</td>
<td>拦截失败</td>
</tr>
<tr>
<td>104</td>
<td>拦截取消</td>
</tr>
<tr>
<td>105</td>
<td>拦截成功</td>
</tr>
<tr>
<td>106</td>
<td>退件签收</td>
</tr>
</tbody>
</table>