快递轨迹地图v2_推荐
<h3>接口描述</h3>
<ul>
<li>向快递公司实时查询物流轨迹信息，在地图上直观地展示包裹的位置和预计送达时间</li>
</ul>
<h3>请求说明</h3>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/express/trace-map/v2</code></p>
<h4>请求方式</h4>
<ul>
<li>POST</li>
</ul>
<h4>请求格式</h4>
<ul>
<li>x-www-form-urlencoded</li>
</ul>
<h4>请求参数</h4>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:400px">说明</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>
<tr>
<td>shipperCode</td>
<td>String</td>
<td>是</td>
<td>快递公司编码，详见：<a href="#快递公司编码对照表">快递公司编码对照表</a></td>
</tr>
<tr>
<td>logisticCode</td>
<td>String</td>
<td>是</td>
<td>快递单号</td>
</tr>
<tr>
<td>phone</td>
<td>String</td>
<td>否</td>
<td>顺丰速运、中通、跨越速运需要传入收或者寄件人手机号或后四位手机号，菜鸟需要输入菜鸟货主编号</td>
</tr>
<tr>
<td>sort</td>
<td>String</td>
<td>否</td>
<td>物流明细排序，desc：倒序，asc：升序，默认desc</td>
</tr>
<tr>
<td>receiverProvinceName</td>
<td>String</td>
<td>否</td>
<td>收件省(如广东省，不要缺少“省”；如是直辖市，请直接传北京、上海等；如是自治区，请直接传广西壮族自治区等)</td>
</tr>
<tr>
<td>receiverCityName</td>
<td>String</td>
<td>否</td>
<td>收件市(如深圳市，不要缺少“市”；如是市辖区，请直接传北京市、上海市等)</td>
</tr>
<tr>
<td>receiverExpAreaName</td>
<td>String</td>
<td>否</td>
<td>收件区/县 (如福田区，不要缺少“区”或“县”)</td>
</tr>
<tr>
<td>receiverAddress</td>
<td>String</td>
<td>否</td>
<td>收件人详细地址 (不用传省市区)</td>
</tr>
<tr>
<td>senderProvinceName</td>
<td>String</td>
<td>否</td>
<td>发件省(如广东省，不要缺少“省”；如是直辖市，请直接传北京、上海等；如是自治区，请直接传广西壮族自治区等)</td>
</tr>
<tr>
<td>senderCityName</td>
<td>String</td>
<td>否</td>
<td>发件市(如深圳市，不要缺少“市”；如是市辖区，请直接传北京市、上海市等)</td>
</tr>
<tr>
<td>senderExpAreaName</td>
<td>String</td>
<td>否</td>
<td>发件区/县 (如福田区，不要缺少“区”或“县”)</td>
</tr>
<tr>
<td>senderAddress</td>
<td>String</td>
<td>否</td>
<td>发件人详细地址 (不用传省市区)</td>
</tr>
</tbody>
</table>
<h4>签名算法说明</h4>
<p><code>sign = sha256(appId + appSecret + timestamp)</code></p>
<p>用服务商分配的 appId、服务商分配的 appSecret，当前时间时间戳 timestamp，按上述顺序拼接成字符串，再进行 sha256 哈希得到。如下：</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>
<h3>返回说明</h3>
<h4>成功返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200,//详见code返回码说明
&quot;charge&quot;: true,//计费标志
&quot;msg&quot;: &quot;成功&quot;,//code 对应的描述
&quot;taskNo&quot;: &quot;967173844153803790618011&quot;,//本次请求号
&quot;data&quot;: {
&quot;deliveryManTel&quot;: &quot;1353928xxxx&quot;,//派件快递员手机号
&quot;receiverCityLatAndLng&quot;: &quot;23.5660600,116.4121100&quot;,//收件城市经纬度
&quot;mapUrl&quot;: &quot;https://express-2.jumdata.com/#/?xxxx&quot;,//轨迹地图URL
&quot;location&quot;: &quot;揭阳市&quot;,//当前城市
&quot;senderCityLatAndLng&quot;: &quot;30.7815290,106.1188890&quot;,//发件城市经纬度
&quot;logisticsStatus&quot;: &quot;3&quot;,//物流状态，详见：物流状态对照表
&quot;logisticsSubStatus&quot;: &quot;301&quot;,//物流子状态，详见：物流状态对照表
&quot;logisticCode&quot;: &quot;77335305877xxxx&quot;,//快递单号
&quot;shipperCode&quot;: &quot;STO&quot;,//快递公司编码
&quot;logisticsList&quot;: [//物流轨迹，文档只展示特定几条
{
&quot;acceptTime&quot;: &quot;2025-05-07 19:47:33&quot;,//轨迹发生时间
&quot;action&quot;: &quot;301&quot;,//物流子状态,同logisticsSubStatus
&quot;location&quot;: &quot;揭阳市&quot;,//节点所在城市
&quot;acceptStation&quot;: &quot;已签收，签收人凭取货码签收。&quot;//轨迹描述
},
{
&quot;deliveryManTel&quot;: &quot;1353928xxxx&quot;,//派件快递员手机号
&quot;deliveryMan&quot;: &quot;李四&quot;,//派件快递员
&quot;acceptTime&quot;: &quot;2025-05-07 14:12:14&quot;,
&quot;action&quot;: &quot;202&quot;,
&quot;location&quot;: &quot;揭阳市&quot;,
&quot;acceptStation&quot;: &quot; 【揭阳市】广东榕城区仙桥街道服务点 的快递员(许铸炼/1353928xxxx)正在为您派送(有事呼叫我，勿找平台，少一次投诉，多一份感恩)&quot;
},
{
&quot;collectManTel&quot;: &quot;1998286xxxx&quot;,//揽收员
&quot;collectMan&quot;: &quot;张三&quot;,//揽收员手机号
&quot;acceptTime&quot;: &quot;2025-05-04 19:08:35&quot;,
&quot;action&quot;: &quot;1&quot;,
&quot;location&quot;: &quot;南充市&quot;,
&quot;acceptStation&quot;: &quot;【南充市】四川南充嘉陵区公司(0817-711xxxx)的吕伏丽(1998286xxxx) 已揽收&quot;
}
]
}
}</code></pre>
<h4>失败返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 400,
&quot;msg&quot;: &quot;快递公司编码不能为空&quot;
}</code></pre>
<h3>返回字段说明</h3>
<table>
<thead>
<tr>
<th>字段名</th>
<th><div style="width:420px">说明</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>计费标志</td>
</tr>
<tr>
<td>taskNo</td>
<td>本次请求号</td>
</tr>
<tr>
<td>data</td>
<td>返回具体结果，object类型，详见data返回字段描述</td>
</tr>
</tbody>
</table>
<h4>code返回码说明</h4>
<table>
<thead>
<tr>
<th>code</th>
<th><div style="width:400px">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>成功（计费）</td>
</tr>
<tr>
<td>400</td>
<td>参数错误</td>
</tr>
<tr>
<td>404</td>
<td>请求地址不正确</td>
</tr>
<tr>
<td>412</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>603</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>
<h3>业务对照表</h3>
<p><a name="快递公司编码对照表"/></p>
<h4>常见快递公司编码对照表</h4>
<table>
<thead>
<tr>
<th><div style="width:100px">快递公司</div></th>
<th>编码</th>
</tr>
</thead>
<tbody>
<tr>
<td>中通快递</td>
<td>ZTO</td>
</tr>
<tr>
<td>申通快递</td>
<td>STO</td>
</tr>
<tr>
<td>圆通速递</td>
<td>YTO</td>
</tr>
<tr>
<td>韵达速递</td>
<td>YD</td>
</tr>
<tr>
<td>邮政快递包裹</td>
<td>YZPY</td>
</tr>
<tr>
<td>EMS</td>
<td>EMS</td>
</tr>
<tr>
<td>顺丰速运</td>
<td>SF</td>
</tr>
<tr>
<td>京东快递</td>
<td>JD</td>
</tr>
<tr>
<td>京东快运</td>
<td>JDKY</td>
</tr>
<tr>
<td>优速快递</td>
<td>UC</td>
</tr>
<tr>
<td>德邦快递</td>
<td>DBL</td>
</tr>
<tr>
<td>极兔速递</td>
<td>JTSD</td>
</tr>
<tr>
<td>菜鸟速递</td>
<td>CNSD</td>
</tr>
<tr>
<td>菜鸟橙运</td>
<td>CNCY</td>
</tr>
<tr>
<td>丹鸟物流</td>
<td>DNWL</td>
</tr>
</tbody>
</table>
<p>全部请下载：[下载快递公司编码对照表](<a href="https://anq-file.oss-cn-hangzhou.aliyuncs.com/support/express/express-code-v2-k.xlsx">https://anq-file.oss-cn-hangzhou.aliyuncs.com/support/express/express-code-v2-k.xlsx</a> "下载快递公司编码对照表")</p>
<h4>物流状态对照表</h4>
<table>
<thead>
<tr>
<th><div style="width:100px">物流主状态</div></th>
<th><div style="width:350px">物流子状态</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>0: 待揽收</td>
<td>0: 待揽收</td>
</tr>
<tr>
<td>1: 已揽收</td>
<td>1: 已揽收</td>
</tr>
<tr>
<td>2: 在途中</td>
<td>201：到达派件城市<br/>202：派件中<br/>204：到达转运中心<br/>205：到达派件网点<br/>206：寄件网点发件<br/>211：已放入快递柜或驿站</td>
</tr>
<tr>
<td>3: 签收</td>
<td>301：正常签收<br/>302：轨迹异常后最终签收<br/>304：代收签收<br/>311：快递柜或驿站签收</td>
</tr>
<tr>
<td>4: 问题件</td>
<td>401：发货无信息<br/>402：超时未签收<br/>403：超时未更新<br/>404：拒收(退件)<br/>405：派件异常<br/>406：退货签收<br/>407：退货未签收<br/>412：快递柜或驿站超时未取<br/>413：单号已拦截<br/>414：破损<br/>415：客户取消发货<br/>416：无法联系<br/>417：配送延迟<br/>418：快件取出<br/>419：重新派送<br/>420：收货地址不详细<br/>421：收件人电话错误<br/>422：错分件<br/>423：超区件</td>
</tr>
<tr>
<td>5: 转寄</td>
<td>5: 转寄</td>
</tr>
<tr>
<td>6: 清关</td>
<td>601：待清关<br/>602：清关中<br/>603：已清关<br/>604：清关异常</td>
</tr>
</tbody>
</table>