快递电子面单
<p>[TOC]</p>
<h3>简介</h3>
<ul>
<li>用于向快递/快运公司下单并获取快递单号。通过快递单号打印面单。</li>
</ul>
<h3>接口调用说明</h3>
<h4>请求方式</h4>
<p>如接口没有单独说明，所有接口均为：<strong>POST</strong></p>
<h4>请求参数</h4>
<p>请求参数包括公共参数和业务参数（业务参数见具体接口说明）
如果请求格式为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: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>计费标志 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:420px;">说明</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>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>
<ul>
<li>用于向快递/快运公司下单并获取快递单号。</li>
</ul>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/express-waybill/order</code></p>
<h4>请求格式</h4>
<ul>
<li>application/json</li>
</ul>
<h4>业务参数</h4>
<ul>
<li>样例</li>
</ul>
<pre><code class="language-json">{
&quot;shipperCode&quot;: &quot;SF&quot;,
&quot;payType&quot;: 1,
&quot;monthCode&quot;: &quot;1234567890&quot;,//不同快递品牌叫法不同，且传参对应的字段不同
&quot;expType&quot;: &quot;1&quot;,
&quot;cost&quot;: 1.0,
&quot;otherCost&quot;: 1.0,
&quot;isReturnPrintTemplate&quot;:&quot;1&quot;,
&quot;templateSize&quot;:&quot;1301&quot;,
&quot;sender&quot;: {
&quot;company&quot;: &quot;&quot;,
&quot;name&quot;: &quot;寄件人姓名&quot;,
&quot;mobile&quot;: &quot;手机号&quot;,
&quot;provinceName&quot;: &quot;浙江&quot;,
&quot;cityName&quot;: &quot;杭州市&quot;,
&quot;expAreaName&quot;: &quot;余杭区&quot;,
&quot;address&quot;: &quot;详细地址&quot;
},
&quot;receiver&quot;: {
&quot;company&quot;: &quot;&quot;,
&quot;name&quot;: &quot;收件人姓名&quot;,
&quot;mobile&quot;: &quot;手机号&quot;,
&quot;provinceName&quot;: &quot;浙江&quot;,
&quot;cityName&quot;: &quot;杭州市&quot;,
&quot;expAreaName&quot;: &quot;余杭区&quot;,
&quot;address&quot;: &quot;详细地址&quot;
},
&quot;commodity&quot;: [
{
&quot;goodsName&quot;: &quot;鞋子&quot;,
&quot;goodsquantity&quot;: 1,
&quot;goodsWeight&quot;: 1.0
},
{
&quot;goodsName&quot;: &quot;衣服&quot;,
&quot;goodsquantity&quot;: 1,
&quot;goodsWeight&quot;: 1.0
}
],
&quot;weight&quot;: 1.0,
&quot;quantity&quot;: 1,
&quot;volume&quot;: 0.0,
&quot;remark&quot;: &quot;小心轻放&quot;
}
</code></pre>
<p>参数说明</p>
<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>payType</td>
<td>String</td>
<td>是</td>
<td>运费支付方式：1：现付，2：到付，3：月结，4：第三方付（顺丰跨越）</td>
</tr>
<tr>
<td>expType</td>
<td>String</td>
<td>是</td>
<td>快递业务类型，，详见快递业务类型</td>
</tr>
<tr>
<td>receiver.company</td>
<td>String</td>
<td>否</td>
<td>收件人公司</td>
</tr>
<tr>
<td>receiver.name</td>
<td>String</td>
<td>是</td>
<td>收件人</td>
</tr>
<tr>
<td>receiver.tel</td>
<td>String</td>
<td>否</td>
<td>电话，电话与手机必填一个</td>
</tr>
<tr>
<td>receiver.mobile</td>
<td>String</td>
<td>否</td>
<td>手机，电话与手机必填一个</td>
</tr>
<tr>
<td>receiver.provinceName</td>
<td>String</td>
<td>是</td>
<td>收件省(如广东省，不要缺少“省”；如是直辖市，请直接传北京、上海等；如是自治区，请直接传广西壮族自治区等)</td>
</tr>
<tr>
<td>receiver.cityName</td>
<td>String</td>
<td>是</td>
<td>收件市(如深圳市，不要缺少“市；如是市辖区，请直接传北京市、上海市等”)</td>
</tr>
<tr>
<td>receiver.expAreaName</td>
<td>String</td>
<td>是</td>
<td>收件区/县(如福田区，不要缺少“区”或“县”)</td>
</tr>
<tr>
<td>receiver.address</td>
<td>String</td>
<td>是</td>
<td>收件人详细地址(不用传省市区)</td>
</tr>
<tr>
<td>receiver.postCode</td>
<td>String</td>
<td>否</td>
<td>收件地邮编，邮政/EMS 必填可填000000</td>
</tr>
<tr>
<td>sender.company</td>
<td>String</td>
<td>否</td>
<td>发件人公司</td>
</tr>
<tr>
<td>sender.name</td>
<td>String</td>
<td>是</td>
<td>发件人</td>
</tr>
<tr>
<td>sender.tel</td>
<td>String</td>
<td>否</td>
<td>电话，电话与手机必填一个</td>
</tr>
<tr>
<td>sender.mobile</td>
<td>String</td>
<td>否</td>
<td>手机，电话与手机必填一个</td>
</tr>
<tr>
<td>sender.provinceName</td>
<td>String</td>
<td>是</td>
<td>发件省(如广东省，不要缺少“省”；如是直辖市，请直接传北京、上海等；如是自治区，请直接传广西壮族自治区等)</td>
</tr>
<tr>
<td>sender.cityName</td>
<td>String</td>
<td>是</td>
<td>发件市(如深圳市，不要缺少“市；如是市辖区，请直接传北京市、上海市等”)</td>
</tr>
<tr>
<td>sender.expAreaName</td>
<td>String</td>
<td>是</td>
<td>发件区/县(如福田区，不要缺少“区”或“县”)</td>
</tr>
<tr>
<td>sender.address</td>
<td>String</td>
<td>是</td>
<td>发件人详细地址(不用传省市区)</td>
</tr>
<tr>
<td>receiver.postCode</td>
<td>String</td>
<td>否</td>
<td>发件地邮编，邮政/EMS 必填可填000000</td>
</tr>
<tr>
<td>quantity</td>
<td>String</td>
<td>是</td>
<td>包裹数，包裹数 (至少填1,最多50)，一个包裹对应一个运单号，Quantity＞1，返回则按照子母件的方式返回母运单号和子运单号</td>
</tr>
<tr>
<td>weight</td>
<td>String</td>
<td>否</td>
<td>包裹总重量kg，京东必填、快运类必填</td>
</tr>
<tr>
<td>volume</td>
<td>String</td>
<td>否</td>
<td>包裹总体积cm3，京东必填、快运类必填</td>
</tr>
<tr>
<td>cost</td>
<td>String</td>
<td>否</td>
<td>快递运费，中通快运（支付方式为到付）必填</td>
</tr>
<tr>
<td>packageType</td>
<td>String</td>
<td>否</td>
<td>木架方式，仅支持跨越速运，10-打卡板， 20-打木架 ，30-打木箱</td>
</tr>
<tr>
<td>remark</td>
<td>String</td>
<td>否</td>
<td>备注</td>
</tr>
<tr>
<td>commodity.goodsName</td>
<td>String</td>
<td>是</td>
<td>商品名称</td>
</tr>
<tr>
<td>commodity.goodsCode</td>
<td>String</td>
<td>否</td>
<td>商品编码</td>
</tr>
<tr>
<td>commodity.goodsQuantity</td>
<td>String</td>
<td>是</td>
<td>商品件数</td>
</tr>
<tr>
<td>commodity.goodsPrice</td>
<td>String</td>
<td>是</td>
<td>商品价格</td>
</tr>
<tr>
<td>commodity.goodsWeight</td>
<td>String</td>
<td>否</td>
<td>商品重量kg</td>
</tr>
<tr>
<td>commodity.goodsDesc</td>
<td>String</td>
<td>否</td>
<td>商品描述</td>
</tr>
<tr>
<td>commodity.goodsVol</td>
<td>String</td>
<td>否</td>
<td>商品体积m³</td>
</tr>
<tr>
<td>isReturnPrintTemplate</td>
<td>String</td>
<td>否</td>
<td>是否返回电子面单模板（默认为0），0：不需要，1：需要</td>
</tr>
<tr>
<td>startDate</td>
<td>String</td>
<td>否</td>
<td>上门揽件开始时间，格式：2025-01-01 17:00:00</td>
</tr>
<tr>
<td>endDate</td>
<td>String</td>
<td>否</td>
<td>上门揽件结束时间，格式：2025-01-01 18:00:00</td>
</tr>
</tbody>
</table>
<h4>成功返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200,//返回码，详见返回码说明
&quot;msg&quot;: &quot;成功&quot;,//返回码对应描述
&quot;taskNo&quot;: &quot;878679153162957225123456&quot;,//本次请求号
&quot;charge&quot;: true,// 计费标志
&quot;data&quot;: {
&quot;printTemplate&quot;: &quot;模板HTML内容&quot;,//面单打印模板内容(html格式)
&quot;order&quot;: {
&quot;shipperCode&quot;: &quot;SF&quot;,//快递公司编码
&quot;orderCode&quot;: &quot;349031603215909075207788&quot;,//订单编号
&quot;originCode&quot;: &quot;571&quot;,//始发地区域编码
&quot;destinatioCode&quot;: &quot;571WB-571&quot;,//目的地区域编码
&quot;logisticCode&quot;: &quot;SF3287043985752&quot;, //快递单号
&quot;signWaybillCode&quot;: &quot;&quot;, //签回单单号
&quot;originName&quot;: &quot;&quot;, //始发地/始发网点
&quot;destinatioName&quot;: &quot;&quot;, //目的地/到达网点
&quot;sortingCode&quot;: &quot;&quot;, //分拣编码
&quot;destinationAllocationCentre&quot;: &quot;&quot;, //目的地分拨
&quot;packageCode&quot;: &quot;&quot; //集包编码
}
}
}</code></pre>
<h4>失败返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 400,// 返回码，详见返回码说明
&quot;taskNo&quot;: &quot;255033697205413852131601&quot;,// 本次请求号
&quot;charge&quot;: false,// 计费标志
&quot;msg&quot;: &quot;快递公司编号不能为空&quot;// 返回码对应描述
}</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>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>
<tr>
<td>安能快递</td>
<td>ANE</td>
</tr>
</tbody>
</table>
<h4>快递业务类型</h4>
<table>
<thead>
<tr>
<th>快递公司</th>
<th>编码</th>
</tr>
</thead>
<tbody>
<tr>
<td>中通快递</td>
<td>23-标准快递、21-中通好快、22-中通标快</td>
</tr>
<tr>
<td>申通快递</td>
<td>1-标准快递、4-生鲜</td>
</tr>
<tr>
<td>圆通速递</td>
<td>1-标准快递、2-圆准达</td>
</tr>
<tr>
<td>韵达速递</td>
<td>1-标准快运、2-韵达智橙网</td>
</tr>
<tr>
<td>邮政快递包裹</td>
<td>1-特快专递 、8-代收到付、9-快递包裹、10-电商标快（仅支持130规格模板）、11-国内标快（仅支持130规格模板）</td>
</tr>
<tr>
<td>EMS</td>
<td>1-特快专递 、8-代收到付、9-快递包裹、10-电商标快（仅支持130规格模板）、11-国内标快（仅支持130规格模板）</td>
</tr>
<tr>
<td>顺丰速运</td>
<td>1-顺丰特快、2-顺丰标快、6-顺丰即日、10-国际小包、12-国际特惠配送、23-顺丰国际特惠(文件)、24-顺丰国际特惠(包裹)、29-国际电商专递-标准、31-便利封/袋(特快)、32-二号便利箱(特快)、33-岛内件(80CM)、35-物资配送、39-岛内件(110CM)、50-千点取60、53-电商盒子F1、54-电商盒子F2、59-E顺递、60-顺丰特快（文件）、61-C1类包裹、111-顺丰干配、153-整车直达、154-重货包裹 （顺丰已下架）、155-标准零担、199-极速包裹、201-冷运标快、202-顺丰微小件、209-高铁专送、215-大票零担、221-香港冷运到家(≤60厘米)、229-精温专递、231-陆运包裹、233-精温专递（样本陆）、235-极效前置-预售、238-纯重特配、242-丰网速运、247-电商标快、250-极置店配（z）、251-极置店配（专线）、252-前置小时达、253-前置当天达、255-顺丰卡航、256-顺丰卡航（D类）、257-退换上门、258-退换自寄、260-入仓电标、261-O2O店配、263-同城半日达、283-填舱标快、285-填舱电标、323-电商微小件</td>
</tr>
<tr>
<td>京东快递</td>
<td>1-京东标快、2-京东特快、3-特瞬送城际、4-生鲜标快（原生鲜特惠） WARMLAYER温层必传、5-生鲜特快 WARMLAYER温层必传、6-函速达、7-特惠包惠、8-特惠小件/京东特惠、9-特快零担、10-特惠重货、11-特快重货、12-快运零担、17-电商标快（原电商特惠）、18-特惠专配</td>
</tr>
<tr>
<td>京东快运</td>
<td>1-京东标快、2-京东特快、3-特瞬送城际、4-生鲜标快（原生鲜特惠） WARMLAYER温层必传、5-生鲜特快 WARMLAYER温层必传、6-函速达、7-特惠包惠、8-特惠小件/京东特惠、9-特快零担、10-特惠重货、11-特快重货、12-快运零担、17-电商标快（原电商特惠）、18-特惠专配</td>
</tr>
<tr>
<td>优速快递</td>
<td>1-标准快递</td>
</tr>
<tr>
<td>德邦快递</td>
<td>1-标准快递、2-微小件特惠、5-大件快递360、6-精准泡货（原重包入户）、10-特快次日（原航空大件次日达）、11-航空大件隔日达、12-特快专递、13-新精准汽运、14-新精准卡航、15-新精准重货、16-泡货特惠、17-特快当日、18-DP联运(K)、19-DP联运(L)、20-重货特惠</td>
</tr>
<tr>
<td>极兔速递</td>
<td>1-标准快递、2-兔优达</td>
</tr>
<tr>
<td>菜鸟速递</td>
<td>1-当日达、2-次日达、3-预约配送、4-当日下午达、5-当日夜间达、6-次日上午达</td>
</tr>
<tr>
<td>菜鸟橙运</td>
<td>1-工作日、2-节假日、101-当日达、102-次晨达、103-次日达、104-预约达</td>
</tr>
<tr>
<td>丹鸟物流</td>
<td>1-标准快递</td>
</tr>
<tr>
<td>安能快递</td>
<td>23-定时达、24-精准零担、95-Mini电商大件、270-普惠达、524-Mini电商小件、546-安心达</td>
</tr>
</tbody>
</table>
<hr />
<h3>面单打印</h3>
<ul>
<li>通过快递单号打印面单。</li>
</ul>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/express-waybill/print</code></p>
<h4>请求格式</h4>
<ul>
<li>application/json</li>
</ul>
<h4>业务参数</h4>
<ul>
<li>样例</li>
</ul>
<pre><code class="language-json">[
{
&quot;orderCode&quot;: &quot;349031603215909075207788&quot;,//面单接口返回的快递单号
&quot;portName&quot;: &quot;NPIEF2738&quot; //打印机名称（如不填则唤起本地默认打印机）
}
]
</code></pre>
<ul>
<li>打印预览需要借助第三方插件C-lodop实现，请提前安装：<a href="http://www.c-lodop.com/download.html">http://www.c-lodop.com/download.html</a>
常见问题："C-Lodop未准备好”或“WebSocket没准备好"。问题原因：系统未识别到C-lodop插件
1、重装C-lodop插件，安装位数和浏览器位数保持一致（32位/64位）
2、浏览器兼容问题，建议谷歌浏览器：手动修改客户浏览器安全设置，在Chrome地址栏输入：chrome://flags/#block-insecure-private-network-requests，看到底色泛黄的“Block insecure...”项的 Default 值，改选成 Disabled，然后窗口下方会出现蓝底的Relaunch按钮，点它重启浏览器。
3、C-Lodop服务端口号被防火墙禁用或被其他程序占用。
4、其他见lodop官网解决方案：<a href="http://www.lodop.net/faq/pp5.html">http://www.lodop.net/faq/pp5.html</a></li>
</ul>
<h4>成功返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200,// 返回码，详见返回码说明
&quot;msg&quot;: &quot;成功&quot;,// 返回码对应描述
&quot;taskNo&quot;: &quot;043439882226367117191234&quot;,// 本次请求号
&quot;charge&quot;: false, // 打印接口不计费
&quot;data&quot;: {
&quot;url&quot;: &quot;https://order-print.jumdata.com/xxxxx.html&quot; //面单打印地址
}
}</code></pre>
<h4>失败返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 400,// 返回码，详见返回码说明
&quot;taskNo&quot;: &quot;255033697205413852131234&quot;,// 本次请求号
&quot;msg&quot;: &quot;快递公司编号不能为空&quot;// 返回码对应描述
}</code></pre>