电子面单云打印接口
菜鸟电子面单的云打印申请电子面单号的方法，本接口支持批量,一次取电子面单号数量请控制在200（含）内。
菜鸟电子面单相关如下接口已升级，在兼容目前现状的基础上， 新增了可选的OAID和tid入参。 当前未接入新方案的订单，需传入空的OAID，和明文的收件人信息。 接入新方案的订单，需传入不为空的 OAID和交易单号tid，新方案中OAID和tid必填。
1.请求参数
请求URL:
POST https://kf.fw199.com/gateway/taobao/cainiao/waybill/v2/batchget
| 参数名 | 类型 | 说明 | 示例 |
|---|---|---|---|
| appid | String | 合作伙伴AppId | uwkahf@jfs92 |
| timestamp | String | 当前时间戳 | |
| tb_seller_nick | String | 淘宝卖家店铺登录账号，非店铺名称 | kingdo |
| request_data | String ， 必填 | 请求生成电子面单的数据，这是一段json格式，具体字段见示例代码 | |
| sysid | String | 100,101,102 | 可空， 代表不同的应用，具体请咨询客服 |
| sign | String | 接口签名 | 如何计算生成见示例代码 |
2. 请求参数request_data的说明
取号支持收件人明文和收件人脱敏（OAID）两种方式。
2.1 收件人明文方式取号
传入recipient.adress.detail（收件人详细地址的明文）、name（收件人姓名的明文）,mobile（收件人手机的明文）， 同时让tid, oaid传入空串。
收件人明文取号请求参数示例如下，以下为request_data的报文数据格式， 请注意数据类型（字符串和数字）的区别：
{
"cp_code": "ZTO", // 必填，物流公司Code， 通过“获取菜鸟标准电子面单模板”接口获取。http://doc.fw199.com/docs/h7b/taobao-cainaio-cloudp-stdtemplate
"dms_sorting": false, // 可填，是否使用智分宝预分拣， 仓库WMS系统对接落地配业务，其它场景请不要使用
"three_pl_timing ": false ,// 订单上是否带3PLtiming属性, 该属性需要严格与订单上属性保持一致，如果不确定，请使用默认false。
"need_encrypt": true , // 注意，设定取号返回的云打印报文是否加密，此值传true，后续淘宝都是返回加密格式了。
"resource_code": "", // 可填， 配送资源code， 仓库WMS系统对接落地配业务，其它场景请不要使用
"sender": { // 必填，发货人信息
"address": { // 必填，发货地址需要符合商家签约的电子面单对应的快递公司网点地址
"city": "长沙市", // 可填， 城市，长度小于20
"detail": "望城大道61号丰树物流园三期（于野彩卡）",// 必填，详细地址，长度小于256
"district": "望城区", // 可填， 区，长度小于20
"province": "湖南省" // 必填， 省，长度小于20
},
"mobile": "1326443654",// 手机号码（手机号和固定电话不能同时为空），长度小于20
"name": "XX印务-as", // 必填，姓名，长度小于40
"phone": "0571232222" // 固定电话（手机号和固定电话不能同时为空），长度小于20
},
"store_code": "", // 可填， 仓code， 仓库WMS系统对接落地配业务，其它场景请不要使用
"trade_order_info_dtos": [ // 必填
{
"object_id": "obj001",// 必填，与业务字段无关，objectId由字母、数字和下划线组成，长度不超过40，只需要在一次请求中保证不同即可。
"order_info": { // 必填， 订单信息
"order_channels_type": "TB",// 必填，订单渠道编码，见 http://doc.fw199.com/docs/h7b/tb-order-channel
"trade_order_list": [ // 必填，订单号（只限传入数字、字母、下划线和中划线，为避免出现冲突，请按电商平台真实订单号传入，请避免使用同个订单号重复取号）
"90020206078841641229"
]
},
"package_info": { // 必填，包裹信息
"id": "pk281", // 必填， 包裹id，用于拆合单场景（只能传入数字、字母和下划线；批量请求时值不得重复，大小写敏感，即123A,123a 不可当做不同ID，否则存在一定可能取号失败）
"items": [ // 必填，商品信息
{
"count": 50, // 必填, 数量
"name": "名片" // 必填，名称
}
],
// "goods_description": "文件", // 顺丰取号必填
"volume": 1, // 可填， 体积, 单位 ml
"weight": 1 // 可填，重量,单位 g
},
"recipient": { // 必填， 收件人信息
"address": { // 必填， 地址
"city": "杭州市", // 可填，城市
"detail": "马泰路38号28弄302", // 详细地址， 可传明文，否则传空串
"district": "桐庐县",// 可填，区
"province": "浙江省", // 必填，省
"town": "横村镇" // 可填，街道
},
"mobile": "13357035578", // 手机号码，可传明文，否则传空串
"name": "洪勇强", // 姓名 ，可传明文，否则传空串
"phone": "057123222233" // 可填，固定电话，
"oaid": "", // 传空串。
"tid" : "" // 传空串。
},
"template_url": "http:\/\/cloudprint.cainiao.com\/template\/standard\/256771\/9", // 必填， 云打印标准模板URL（组装云打印结果使用，值格式http://cloudprint.cainiao.com/template/standard/${模板ID}）
"user_id": 0 , // 必填， 请传固定传0，蜂巢开放平台会转处理。
// "logistics_services":"{\"ZTKY-SERVICE\":{\"type\":\"SEND\"}}" //需要快递公司的增值服务，则传入。 具体见https://support-cnkuaidi.taobao.com/doc.htm#?docId=106156&docType=1
}
]
}2.2 收件人密文（OAID)方式取号
传入tid,oaid 。recipient.adress.detail（收件人详细地址）、name（收件人姓名）,mobile（收件人手机）传入订单中的原始订单中的相应数据即可。说明：由于淘宝侧收件人信息字段不允许为空，所以脱敏的收件人信息也需要传入。
收件人脱敏（OAID)方式取号请求参数示例如下，以下为request_data的报文数据格式， 请注意数据类型（字符串和数字）的区别：
{
"cp_code": "ZTO", // 必填，物流公司Code， 通过“获取菜鸟标准电子面单模板”接口获取。http://doc.fw199.com/docs/h7b/taobao-cainaio-cloudp-stdtemplate
// "brand_code": "FW", // 如果是顺丰取号，必填，FW代表丰网
"dms_sorting": false, // 可填，是否使用智分宝预分拣， 仓库WMS系统对接落地配业务，其它场景请不要使用
"three_pl_timing ": false ,// 订单上是否带3PLtiming属性, 该属性需要严格与订单上属性保持一致，如果不确定，请使用默认false。
"need_encrypt ": true , // 注意，设定取号返回的云打印报文是否加密，此值传true，后续淘宝都是返回加密格式了。
"resource_code": "", // 可填， 配送资源code， 仓库WMS系统对接落地配业务，其它场景请不要使用
"sender": { // 必填，发货人信息
"address": { // 必填，发货地址需要符合商家签约的电子面单对应的快递公司网点地址
"city": "长沙市", // 可填， 城市，长度小于20
"detail": "望城大道61号丰树物流园三期（于野彩卡）",// 必填，详细地址，长度小于256
"district": "望城区", // 可填， 区，长度小于20
"province": "湖南省" // 必填， 省，长度小于20
},
"mobile": "1326443654",// 手机号码（手机号和固定电话不能同时为空），长度小于20
"name": "XX印务-as", // 必填，姓名，长度小于40
"phone": "0571232222" // 固定电话（手机号和固定电话不能同时为空），长度小于20
},
"store_code": "", // 可填， 仓code， 仓库WMS系统对接落地配业务，其它场景请不要使用
"trade_order_info_dtos": [ // 必填
{
"object_id": "obj001",// 必填，与业务字段无关，objectId由字母、数字和下划线组成，长度不超过40，只需要在一次请求中保证不同即可。
"order_info": { // 必填， 订单信息
"order_channels_type": "TB",// 必填，订单渠道编码，见 http://doc.fw199.com/docs/h7b/tb-order-channel
"trade_order_list": [ // 必填，订单号（只限传入数字、字母、下划线和中划线，为避免出现冲突，请按电商平台真实订单号传入，请避免使用同个订单号重复取号）
"90020206078841641229"
]
},
"package_info": { // 必填，包裹信息
"id": "pk281", // 必填， 包裹id，用于拆合单场景（只能传入数字、字母和下划线；批量请求时值不得重复，大小写敏感，即123A,123a 不可当做不同ID，否则存在一定可能取号失败）
"items": [ // 必填，商品信息
{
"count": 50, // 必填, 数量
"name": "名片" // 必填，名称
}
],
// "goods_description": "文件", // 顺丰取号必填
"volume": 1, // 可填， 体积, 单位 ml
"weight": 1, // 可填，重量,单位 g
"total_packages_count ": 1 // 可填，子母件模式中的总包裹数/总件数，用于打印当前包裹处于总件数的位置比如5-2，可以表示总包裹数为5，当前为第2个包裹，只有快运公司需要传入，其他的可以不用传入
},
"recipient": { // 必填， 收件人信息
"address": { // 必填， 地址
"city": "杭州市", // 城市，必填，按原订单原样传入
"detail": "马泰路**号**弄**", // 必填，按原订单原样传入
"district": "桐庐县",// 区，必填，按原订单原样传入
"province": "浙江省", //省， 必填，按原订单原样传入
"town": "横村镇" // 街道 ，必填，按原订单原样传入
},
"mobile": "*******5578", // 手机号码，按原订单原样传入
"name": "洪**", // 姓名 ， 按原订单原样传入
"phone": "" // 可填，固定电话，
"oaid": "1h12M4LqkhUkt1ibEk6VyZv2gRsECYSQayzH33CwBP1s3CmkVyx1m4SItNJ6ZhgUibyzr9RA", // oaid模式，必传。
"tid" : "371834183481243" //订单号，如果采用oaid模式，tid必传。
},
"template_url": "http:\/\/cloudprint.cainiao.com\/template\/standard\/256771\/9", // 必填， 云打印标准模板URL（组装云打印结果使用，值格式http://cloudprint.cainiao.com/template/standard/${模板ID}）
"user_id": 0, // 必填， 请传固定传0，蜂巢开放平台会转处理。
// "logistics_services":"{\"ZTKY-SERVICE\":{\"type\":\"SEND\"}}" //需要快递公司的增值服务，则传入。 具体见https://support-cnkuaidi.taobao.com/doc.htm#?docId=106156&docType=1
}
]
}
3. 请求示例代码(Java)
@Test
public void getCaiNiaoWayBillGet() throws Exception {
String tb_seller_nick = Config.TBSellerNick ;
String reqeustData ="{\"cp_code\":\"ZTO\",\"dms_sorting\":false,\"resource_code\":\"\",\"sender\":{\"address\":{\"city\":\"长沙市\",\"detail\":\"望城大道61号丰树物流园三期（于野彩卡）\",\"district\":\"望城区\",\"province\":\"湖南省\"},\"mobile\":\"1326443654\",\"name\":\"XX印务-as\",\"phone\":\"0571232222\"},\"store_code\":\"\",\"trade_order_info_dtos\":[{\"object_id\":\"1\",\"order_info\":{\"order_channels_type\":\"TB\",\"trade_order_list\":[\"90020206078841641229\"]},\"package_info\":{\"id\":\"1\",\"items\":[{\"count\":50,\"name\":\"名片\"}],\"volume\":1,\"weight\":1},\"recipient\":{\"address\":{\"city\":\"杭州市\",\"detail\":\"横村镇桐千路8118号华艺大酒店单身公寓12楼\",\"district\":\"桐庐县\",\"province\":\"浙江省\",\"town\":\"横村镇\"},\"mobile\":\"13357035578\",\"name\":\"洪勇军修改-智能发货\",\"phone\":\"057123222233\"},\"template_url\":\"http:\\/\\/cloudprint.cainiao.com\\/template\\/standard\\/256771\\/9\",\"user_id\":0}]}";
//业务参数
Map<String, String> data = new HashMap<String, String>();
data.put("appid", Config.AppId);
data.put("sysid", "100"); // 此值很重要，代表不同的应用，否则拉到订单，具体请咨询客服。
data.put("tb_seller_nick", tb_seller_nick);
Long timestamp = System.currentTimeMillis() / 1000;
data.put("timestamp", timestamp.toString());
data.put("request_data",reqeustData );
data.put("sign", Utils.Sign(data,Config.AppSecret));
// 调用服务API
doHttpRequest(Config.TaoBaoCaiNiaoWayBillGetUrl ,data);
}
5. 取号返回结果如下 ：
{
"code": 0,
"message": "ok",
"data": [{
"object_id": "1",
"print_data": {
"encryptedData": "AES:rU904rj6UH2oqfSUb43+Z5CuoOkTVqESmlQ0tcJbrUB/5N9/gQ8ip5WXveG3gimRDSEDFI6dkybC2/2u4uS/NHenN2FdWeJosiEIFQwiVJneFTe1d3fGi6rHHQaVG+lwX8ySZQ4vxZD35xh9QHRYgi4j76aQs9rpiAwLwWYOg48IL8yugsSYyKap/pLSnRjfg+uyFrAcSp87gPY2Hh9cSVw1+PbaM2hSYR1IV3dafCIAVuPW1sygkGNvuYo4x4FK8Gw/R11A/mpp/neGRhz9UXQCSjrf39JQnWolJohMvSjCWoyA1hQrNc3qRIJJ5YnwwmdIpV7reKGgpmLga/ZREK8Thtnmd5lNrpJZtJrDpeObSjPeLypJRoO/7OTr63m5Cr2KsViJvo3iYIZF1CjAkPWVfLyEJ1bqefuxy0ymIJOqXYdribSMMhDxNKVdR4rYUtV0OCbKfQB60oIhGW5zoPEz1S5hBru5gKGdFzs99ZgCKqtWa0DnOzrZDXroU1mhurtlulE8QbipInu63fkIwn3h9ZSK0sMyV5Jrk5x3MIJi23SfGrjIoCfoCobpPbxk0aOBtij8c0+n/BT65eUt1IG3UWJ+lOluqguQI/n7yYap9sXI/Qf2JVNBAx5WMyuffMqB38o+woAgvr1MKjGDdDCy1vridDf3f3wksV1oeY+LCtGJIf0KNtofAOu7QDE+h5asLOdqdbEvLr8PThwSKdhN613ausm+y8+shsf0eGX0i0/QC1axwJhtECUATEsBaVS196TxRRrwxTjtaetzLkWLMf5XVgQqiYe782c1K5Jpf7x1DgXA8FciWw2xkVbDrmDcmtI7/IySDypicsuSZB/A2OCNkrl/esyoSmOLMiRncDoGybssSQM7H0dR8jO1+l8ovVXuIimdhIJVRL86ggxi1BIAPWBfFLiELNaHq1gE6fsyQraHQXWdSmmQPg4OAXM553cx3Vld/qNQ4WBBy+S4kxCYq8nqKyWRWLhoIcCF4tV0WpDZmF4yLLiNkZSisRnQinJDGOvZN/7O96rCGbHMADcA6KKhVreGljeCJtIDSyBD4bQIPCzV1tIhNwOJnzwsucn/wrFt70cgEq3m1WjfQlPRyezaWNR0XJJ+4L3X3JYMIYxiTEmVEkkKim5X7KkbfBvbyrHzAMqHrQuVl2W7jhmnm356axsfovFuhY+wU3tCHTlq65g6W614gsI6ENU2xQWE8/gfY5zES88HqR77oN7M1x204dXXErdIMaCe5kULZipdV4GIeXa1LzYVfo/k8KBQHH7lJTegbVsd9mFIPKc2WZpYEiPvMggzQCOs6/6zvxlrGg0a0AtPNRP2pC9oqSW0YFOUEPt9Dd060nhn6uDYD8N2N/P8QB8NxIef7kixV3cPiSYwf08Dop+fSGF2fL6gVJt7n8DevUeUBfVAYRHtLZ3G50dc5hQzgnMhIvB2xL5yN09rVE+6TQnuZqc3gDUhbyQQij/cOB0olIlJhAXY6AXWi2PQoHQdDAr3LzHIAPFs1v0BA62bihGU1M3nIBEzNWPjPCzjr4dbGs0hb8LH5uKD4HfieVjsSh+I8fz3JolKKkrKZUc5DS/6",
"signature": "MD:VSbZrJztIQOONeMW6QyGSA==",
"templateURL": "http://cloudprint.cainiao.com/template/standard/256771/9",
"ver": "waybill_print_secret_version_1"
},
"waybill_code": "773094391370057",
"code": 0,
"message": ""
}]
}失败的情况
{"code":200,"message":"请求的request_data数据格式错误","trace_id":""}说明： code为0表示成功，非0为失败，message会包含失败原因。 data字段包含数据字段说明：。
如果外层code非0，则整个失败了，比如传入的参数错误了，此时不用判断内层的code。 如果外层的code是成功的，最好还要判断一个内层的code是否为0，因为批量取号时，可能有些订单成功，有些订单失败了
上述返回参数的云打印内容(print_data)的具体解释链接请点击 此处链接
6.常见问题
Q:关于重复取号问题
A:电子面单取号幂等是根据 快递公司编码cpCode、渠道编码order_channels_type： 、商家user_id、包裹号 package_info.id 、订单号trade_order_list , 进行幂等。如果两次请求的这些参数相同，会返回第一次请求的面单号和面单信息。通过本接口获取到电子面单号和打印模板这些数据后，如何打印？
A: 得到打印面单信息，根据打印组件发送协议要求，拼装打印请求，向打印组件发送打印消息，进行打印。 见文档：https://open.taobao.com/doc.htm?docId=107014&docType=1Q:批量取号时如果失败了，会返回成功的部分吗？
A: 比如一次取100个面单号，会返回100个结果，包括成功和失败的。 可以根据data集合中的code来判断，code为0时，表示对应的快递单取号成功了，如果失败了code为1，message会有失败的原因。 对于失败的订单号，可以根据自定义传入的object_id（可以用订单号等做相应的标识）定位是哪个订单取号失败。
Q: 接口返回错误信息:发货地址没有匹配的电子面单服务
A: 取号店铺的淘宝后台电子面单里签约的快递的发货地址（通过此接口获取严格的省，市，区，详细地址格式）， 和你取号时的发货地址要一样的，特别像东莞这种地方，注意区district字段 。分拣信息，大头笔、三段码、集包地为空的情况
分拣信息是物流公司对包裹分拣、路由的有效信息，包括集包地、大头笔、三段码/二段码。
分拣信息根据收发地址进行计算得到，通过电子面单取号接口返回。
大头笔：是给始发分拨用的，标记的是末端分拨中心，大头笔的概念与三段码中的第一段码重合。不同的快递公司，有不同的大头笔写法，有的使用汉字，有的使用数字等，其中圆通规定，如果有二段码，直接使用二段码，不打印大头笔，其实圆通的二段码中用‘-’分隔两段信息，内部嵌入了第一段码的信息。
三段码/二段码：第一段代表末端分拨中心，第二段代表末端网点，第三段代表末端网点下的承包区或者派件员；三段码以空格拼接在大头笔后面，有则拼接，无则空白。
集包地：始发网点发给下网点的货物中，将同一终到网点或省份的快件装在一个容器内合并转运。该容器在操作的一个或多个环节中不需要打开，仅被视为一票货物操作。同时，针对集装包标签所进行的扫描在系统中都会被视为针对包中所有快件的收到和发出扫描。
目前分拣信息上有时会返回数字，这种是正常的，是物流公司的编码。
有些情况分拣信息没有计算出，返回为空。这种情况一般是收货地址没有按照淘系地址，需要对接 taobao.logistics.address.search 接口，将地址转成淘系地址再申请面单号。
对于一些地址为高新区、其它区的地址，是难以计算分拣信息的，需要商家提供更细致的地址才能够计算。
下面几种情况是得不到分拣信息的：
- 没有 区、街道信息： province:浙江省;city：杭州市;detial:西溪园区四号楼
- 区 为其它区，高新区之类： province:浙江省;city：杭州市; district:其它区; detial:西溪园区四号楼
电子面单取号接口调用成功后，会根据所传收货地址在print_data中返回分拣信息，但是经常会出现无分拣信息，大头笔、三段码、集包地为空的情况。
当出现上述情况，处理建议如下：
1、请确保收货地址中省、市、区及详细地址 准确、精确，地址不够详细，将出现末段网点匹配率低等情况，无法返回分拣信息；
2、电子面单系统在生成面单时，可能会出现分拣信息计算系统超时，这会导致生成的面单没有任何分拣信息，虽然概率比较小，但是会发生，也属于正常的情况，快递公司不能拒收这样的件。遇到这样的情况，建议取消面单，重新获取单号，或者换一家快递公司获取单号。
注意：未返回分拣信息，主要的处理方式是取消已生成单号，重新取号；多次取消重取依然无分拣信息返回，建议切换快递公司取号。
ps：批量取号，同一批次如出现一单分拣信息计算超时，则此批次所有单号都不会返回分拣信息。
接口返回fail to apply new waybillcode
当收件人地址中含有错别字、生僻字时，就会出现此提示。原因是菜鸟不接受这些生僻字，就会提示 fail to apply new waybillCode。所以，遇到 fail to apply new waybillCode 提示时，请仔细检查地址，将错别字、生僻字修正，或者删除，或者用其它字代替。菜鸟打印组件提示，无效的加密数据
为提升快递公司操作的准确性和操作效率更好地服务商家和消费者，推动所有与菜鸟电子面单平台接入的系统服务商进行系统一致性改造升级。
升级后对取号接口返回数据和云打印发送打印的标准面单数据进行了加密处理，有些用户发送加密的打印数据，提示无效的加密数据错误用户操作系统里面的系统日期和时间必须是正确的，系统时间正确的情况下，可能导致报错的原因：
1.确认操作系统是否是xp
解决方法：目前是监听dns解析来确定网络是否可用的，xp的这块api不支持。建议升级操作系统为win7及以上版本。
2.确认安装的是云打印客户端最新版本
3.确认用户网络环境稳定。
4.必须保证云打印资源域名通过浏览器可以正常访问：cloudprint.cainiao.com , cdn-cloudprint.cainiao.com
无法访问云打印资源域名，可能是dns有问题，可以按照下面的步骤进行设置：尝试使用阿里云 dns，建议使用阿里云dns(223.5.5.5 223.6.6.6)
如果使用阿里云 dns 无效，尝试选择，对应服务商的 dns
步骤2无效，尝试自动获取 DNS（不要指定 DNS）
配置dns后，重启电脑后才可以生效，建议重启一下再试。5.上述情况都排查无误的情况下，可能是isv打单软件实现的问题，打单软件处理的打印数据本身有问题，导致无法解密。
解决方法：isv仔细阅读一致性改造白皮书，检查自己发送打印的数据内容和格式是否符合要求。丰网取号时传cp_code为LE09252050
顺丰取号时返回提示”错误描述：sf_response_fail-20005-参数orderId超过最大长度64“
orderId 是 tradeOrderList + packageId + userid 拼起来的，所以要一起看，总长度不能超过64位
