菜鸟电子面单ISV云打印组件一致性改造心得
19年2月末,阿里/淘宝旗下菜鸟电子面单平台发布了电子面单一致性改造的通知.
简单说,就是原来用订单(或者包裹)信息进行取号的时候,是明文数据传送给淘宝,然后淘宝会明文传送回.原因,在文后分析
现在,改为明文请求密文返回的方式来交换数据.
改造心得:
整体的改造还是比较简单的,就是原来的Data字段变成了现在的encryptedData
直接传给打印组件就可以了. 还省去了解析原来的Data字段了.
但是在容错率提升的同时,不能修改一些面单上的信息了(除了发货地址以外)
在与云打印组件对话时,
修改发货地的方式,是保持encryptedData字段不变的情况下,在发给打印机的数据里面增加了addData的字段传递,菜鸟云打印组件如果接收到这个addData字段的数据的话,会在自己解密了打印信息以后用传入的addData覆盖原本的发货地址信息.详细操作步骤和addData的添加方式和字段位置见下文.
原来的ISV自定义字段和商家字段的传参方式保持不变
我的项目是C#,但是其他语言也一样的概念,只是代码编译方式不同,json数据对了就可以
改造前:
请求的ParamWaybillCloudPrintApplyNewRequest_
{
"cp_code": "ZTO",
"sender": {
"address": {
"city": "秦皇岛市",
"detail": "燕山大街/东港路 某个小区8-1",
"district": "海港区",
"province": "河北省"
},
"mobile": "13222225555",
"name": "王先生",
"phone": ""
},
"trade_order_info_dtos": [{
"object_id": "60658",
"order_info": {
"order_channels_type": "OTHERS",
"trade_order_list": ["100000046434"]
},
"package_info": {
"id": "60658",
"items": [{
"count": 1,
"name": "多面单专用商品不出售"
}],
"volume": 0,
"weight": 0
},
"recipient": {
"address": {
"city": "秦皇岛市",
"detail": "另外一个小区111",
"district": "海港区",
"province": "河北省"
},
"mobile": "13333334444",
"name": "王工",
"phone": ""
},
"template_url": "http://cloudprint.cainiao.com/template/standard/301/197",
"user_id": 11115975
}]
}接收的CainiaoWaybillIiGetResponse
{
"cainiao_waybill_ii_get_response": {
"modules": {
"waybill_cloud_print_response": [{
"object_id": "60658",
"print_data": "{\"data\":{\"_dataFrom\":\"waybill\",\"cpCode\":\"ZTO\",\"needEncrypt\":false,\"packageInfo\":{\"id\":\"60658\",\"items\":[{\"count\":1,\"name\":\"多面单专用商品不出售\"}],\"volume\":0,\"weight\":0},\"parent\":false,\"recipient\":{\"address\":{\"city\":\"秦皇岛市\",\"detail\":\"另外一个小区111\",\"district\":\"海港区\",\"province\":\"河北省\"},\"mobile\":\"13333334444\",\"name\":\"王工\",\"phone\":\"\"},\"routingInfo\":{\"consolidation\":{\"name\":\"秦皇岛\"},\"origin\":{\"code\":\"33510\",\"name\":\"秦皇岛\"},\"receiveBranch\":{\"code\":\"32102\"},\"routeCode\":\"40-4 80\",\"sortation\":{\"name\":\"852-\"},\"startCenter\":{},\"terminalCenter\":{}},\"sender\":{\"address\":{\"city\":\"秦皇岛市\",\"detail\":\"燕山大街\/东港路 某个小区8-1-102\",\"district\":\"海港区\",\"province\":\"河北省\"},\"mobile\":\"13222225555\",\"name\":\"王先生\",\"phone\":\"\"},\"shippingOption\":{\"code\":\"STANDARD_EXPRESS\",\"title\":\"标准快递\"},\"waybillCode\":\"75133154963040\"},\"signature\":\"MD:2wjhlt4GSYQSzKBhIfr4rQ==\",\"templateURL\":\"http:\/\/cloudprint.cainiao.com\/template\/standard\/301\/197\"}",
"waybill_code": "75133154963040"
}]
},
"request_id": "107bh2i8ul2fi"
}
}发送给打印机的数据的Data模块内容:
{
"data": {
"_dataFrom": "waybill",
"cpCode": "ZTO",
"needEncrypt": false,
"packageInfo": {
"id": "60658",
"items": [{
"count": 1,
"name": "多面单专用商品不出售"
}],
"volume": 0,
"weight": 0
},
"parent": false,
"recipient": {
"address": {
"city": "秦皇岛市",
"detail": "另外一个小区111",
"district": "海港区",
"province": "河北省"
},
"mobile": "13333334444",
"name": "王工",
"phone": ""
},
"routingInfo": {
"consolidation": {
"name": "秦皇岛"
},
"origin": {
"code": "33510",
"name": "秦皇岛"
},
"receiveBranch": {
"code": "32102"
},
"routeCode": "40-4 80",
"sortation": {
"name": "852-"
},
"startCenter": {},
"terminalCenter": {}
},
"sender": {
"address": {
"city": "秦皇岛市",
"detail": "燕山大街/东港路 某个小区8-1-102",
"district": "海港区",
"province": "河北省"
},
"mobile": "13222225555",
"name": "王先生",
"phone": ""
},
"shippingOption": {
"code": "STANDARD_EXPRESS",
"title": "标准快递"
},
"waybillCode": "75133154963040"
},
"signature": "MD:2wjhlt4GSYQSzKBhIfr4rQ==",
"templateURL": "http://cloudprint.cainiao.com/template/standard/301/197"
}之前修改发货人地址的时候是这样:
bag.WaybillCodeInfo.PrintData.data.sender.address.detail = bag.MarkPaperInfo.SenderAddress;
bag.WaybillCodeInfo.PrintData.data.sender.address.city = bag.MarkPaperInfo.SenderCity;
bag.WaybillCodeInfo.PrintData.data.sender.address.district = bag.MarkPaperInfo.SenderArea;
bag.WaybillCodeInfo.PrintData.data.sender.address.province = bag.MarkPaperInfo.SenderState;
发送给打印机的任务Json
{
"task": {
"taskID": "60658",
"preview": false,
"printer": "\\\\192.168.1.128\\qr-668 label (\u526F\u672C 1)",
"previewType": "pdf",
"firstDocumentNumber": 0,
"totalDocumentCount": 1,
"documents": [{
"documentID": "60658",
"contents": [{
"data": {
"cpCode": "ZTO",
"needEncrypt": false,
"parent": false,
"recipient": {
"address": {
"city": "\u79E6\u7687\u5C9B\u5E02",
"detail": "\u751F\u6001\u8C37111",
"district": "\u6D77\u6E2F\u533A",
"province": "\u6CB3\u5317\u7701"
},
"mobile": "13333334444",
"name": "\u738B\u5E05",
"phone": ""
},
"routingInfo": {
"consolidation": {
"name": "\u79E6\u7687\u5C9B"
},
"origin": {
"code": "33510",
"name": "\u79E6\u7687\u5C9B"
},
"routeCode": "40-4 80",
"sortation": {
"name": "852-"
}
},
"sender": {
"address": {
"city": "\u79E6\u7687\u5C9B\u5E02",
"detail": "",
"district": "\u6D77\u6E2F\u533A",
"province": "\u6CB3\u5317\u7701"
},
"mobile": "13222225555",
"name": "\u738B\u5148\u751F",
"phone": ""
},
"shippingOption": {
"code": "STANDARD_EXPRESS",
"title": "\u6807\u51C6\u5FEB\u9012"
},
"waybillCode": "75133154963040"
},
"signature": "MD:2wjhlt4GSYQSzKBhIfr4rQ==",
"templateURL": "http://cloudprint.cainiao.com/template/standard/301/197"
}, {
"data": {
"Pid": "60658",
"ReceiverName": "\u738B\u5E05"
},
"templateURL": "http://cloudprint.cainiao.com/template/standard/226109"
}]
}]
},
"cmd": "print",
"requestID": "636875771840958663"
}改造后
请求的ParamWaybillCloudPrintApplyNewRequest_
{
"cp_code": "ZTO",
"need_encrypt": true,
"sender": {
"address": {
"city": "秦皇岛市",
"detail": "燕山大街/东港路 某个小区8-1-102",
"district": "海港区",
"province": "河北省"
},
"mobile": "13222225555",
"name": "王先生",
"phone": ""
},
"trade_order_info_dtos": [{
"object_id": "60658",
"order_info": {
"order_channels_type": "OTHERS",
"trade_order_list": ["100000046434"]
},
"package_info": {
"id": "60658",
"items": [{
"count": 1,
"name": "多面单专用商品不出售"
}],
"volume": 0,
"weight": 0
},
"recipient": {
"address": {
"city": "秦皇岛市",
"detail": "另外一个小区111",
"district": "海港区",
"province": "河北省"
},
"mobile": "13333334444",
"name": "王工",
"phone": ""
},
"template_url": "http://cloudprint.cainiao.com/template/standard/301/197",
"user_id": 11115975
}]
}返回的 CainiaoWaybillIiGetResponse
{
"cainiao_waybill_ii_get_response": {
"modules": {
"waybill_cloud_print_response": [{
"object_id": "60658",
"print_data": "{\"encryptedData\":\"AES:rU904rj6Nyk5khtZzzPiB8ihChBYzveb2VHK04HKmM8oNePp9rvU7pYioYfPi2GgLf3+imrux4I6pw69ra6K1Jo9nag\/MMeVCeK0esCHNsZy4dw+oblBmnMHbNENnMvVQ4EsA==\",\"signature\":\"MD:zpGzg2J55pA4raupY8OUjw==\",\"templateURL\":\"http:\/\/cloudprint.cainiao.com\/template\/standard\/301\/197\",\"ver\":\"waybill_print_secret_version_1\"}",
"waybill_code": "75133154963040"
}]
},
"request_id": "bf3ov76162px"
}
}发送给打印机的数据的Data模块内容:
{
"encryptedData": "AES:rU904rj6UH2oqfSUb43+Z+XlOkZaULeerkScS5xbmfgjZGHz4gle6o/TrLQdV8wRsrsk0TObjJaJI5n4tAPV1k+iIWV1MKLLinemJCMlkG4E4NH7x2VQc6HeFmVysCI3xZNfkUAB8e1hjRPZxC9VzplGuDUZdEjCNJZhpj9EOuKW4Jb+6ioUlazIdDxZwrWF28T3rd2TZAB4CtI6CVPf3STadbBI1MM0zrXTSTvBCjXV8+PvVm1DzlIycpNbwdpGxXfu7lyjMaiybrMMb/Bzgv8LFbYSbC9SVvJP5dGUfRqD3Z8SOJbHtQ75ogARUNPezD9E3vix2j4jkWB4F8ECxwtHlSJzckNOpeNfrbdmEYds+LVeUusXuHCZliD8vsZfTt9kZO0ZmNfYvj3iUaKD4nne8PNcimn7ulDT80TSLCfFsS2W6VJDdeXd3LMkz544mM4P2DTck5dT9Ks914O9s6GuGiYg39MmuTzPSXiCyeeBxtktbzn8DmbB8Xqpii7nKWYhSHoy+mRptMZCgTWHr02WwO8EntHlvbvy4w8y8tulpAuF5RvB5QIoq2pBVpSIyDZ8pp+760l3rzHqf3ATF6eH613oJYxyVpwMzdkKkhT9hmdbXxV9NOzBpMx6Rxt4aN9CU9HJ7NpY1HRckn7gvasdDZTLUl+52paYk4dPNe701FqQuTYKtZp5dkgD2QtXMlWXzfSYRcmEy2XRIAhhPajqKv9we63XvZH7oXFuvLSdR1soCD5s+NzNECITQt8FSA/Tqs1dFsx+l3R1x3FhVyJPt5uy2LJpimgWxSciYYDwyY13qb9UznL0B+nL0slUX61H5RLoj69DBnKxH5T3nuRPgUJTn3R+8jremNi8pmXLlazPoI9zpT2wUjZhu8QhSovDBjZmEZ52MRiDlyiKOM2EELuKCW45LEZpAkqVbgPqDpIurt1u8BWcuj92wWkMo7ewpITicJXy4JZ1PUuyeAxo2YiWp9f9CCA/ZQ8kdF77JCBtEcRInsUt3YSBxH04fB/keGNQx1SzioMJkw65WfmoCNyk5khtZzzPiB8ihChBYzveb2VHK04HKmM8oNePp9rvU7pYioYfPi2GgLf3+imrux4I6pw69ra6K1Jo9nag/MMeVCeK0esCHNsZy4dw+oblBmnMHbNENnMvVQ4EsA==",
"signature": "MD:zpGzg2J55pA4raupY8OUjw==",
"templateURL": "http://cloudprint.cainiao.com/template/standard/301/197",
"ver": "waybill_print_secret_version_1"
}现在修改发货人地址的时候是这样:
bag.WaybillCodeInfo.PrintData.addData.sender.address.detail = bag.MarkPaperInfo.SenderAddress;
bag.WaybillCodeInfo.PrintData.addData.sender.address.city = bag.MarkPaperInfo.SenderCity;
bag.WaybillCodeInfo.PrintData.addData.sender.address.district = bag.MarkPaperInfo.SenderArea;
bag.WaybillCodeInfo.PrintData.addData.sender.address.province = bag.MarkPaperInfo.SenderState;
bag.WaybillCodeInfo.PrintData.addData.sender.mobile = bag.MarkPaperInfo.SenderMobile;
bag.WaybillCodeInfo.PrintData.addData.sender.phone = bag.MarkPaperInfo.SenderPhone;
bag.WaybillCodeInfo.PrintData.addData.sender.name = bag.MarkPaperInfo.SenderName;
改完了发货人地址信息后,
完整的发送给打印机的内容为:
{
"task": {
"taskID": "60658",
"preview": false,
"previewType": "pdf",
"firstDocumentNumber": 0,
"totalDocumentCount": 1,
"documents": [{
"documentID": "60658",
"contents": [{
"encryptedData": "AES:rU904rj6UH2oqfSUb43+Z范德萨发生范德萨sZy4dw+oblBmnMHbNENnMvVQ4EsA==",
"signature": "MD:zpGzg2J55pA4raupY8OUjw==",
"templateURL": "http://cloudprint.cainiao.com/template/standard/301/197",
"ver": "waybill_print_secret_version_1",
"addData": {
"sender": {
"address": {
"province": "\u6CB3\u5317\u7701",
"city": "\u79E6\u7687\u5C9B\u5E02",
"district": "\u6D77\u6E2F\u533A",
"detail": ""
},
"name": "\u738B",
"mobile": "13333332222",
"phone": ""
}
}
}, {
"data": {
"OpreateCode": "A14-1",
"Pid": "60658",
"ReceiverName": "\u738B"
},
"templateURL": "http://cloudprint.cainiao.com/template/standard/226109"
}]
}]
},
"cmd": "print",
"requestID": "636887028856620110"
}注意adddata的位置 是放在contents下面的.并且注意adddata的结构层次关系
附上一个菜鸟云组件的测试连接:
http://cdn-cloudprint.cainiao.com/waybill-print/docs/test/test_print.html
总结:
总体上没有什么难度,我的代码只需要1小时内改好.
但是有一个问题是需要注意的,
之前的未加密结构中,contents字段下(contents内是data结构的数组元素),包了一个data,在data结构内的字段是打印内容的正文,然后和data同级的再加你自己的ISV自定义内容区或者是商家自定义区的参数的结构体即可.
现在加密的结构中.contents字段下,原第一个数组元素的data结构内的字段直接提升一个层级,也就是不需要data->encryptedData这样使用了,而是把encryptedData直接提出来跟自定义区域的data结构同一层级.
上个图大家就明白了.
改造之前的结构
改造之后的结构
注意改造后要升级客户机的菜鸟云打印组件版本,否则是解析不出来密文数据打印不出来快递单的.
祝各位改造顺利.如有问题请留言.
关于菜鸟电子面单的一切问题欢迎咨询.
宣传内容:
各ERP和电商平台系统软件,打单软件,欢迎对接我的地址解析系统,
中文地址自动解析,适合餐饮APP,物流APP,用户注册,快递打单,信息收录,微商等
一切需需要使用到地址的应用场景.毫秒级响应,自动过滤关键字,自动补全
使用成本低,对接简单,其智能识别效率为行业标杆,且全网首发,欢迎您的使用
如:尚志市亚布力滑雪场王先生13333335555 自动解析结果为
又如:
收件地址:桂林七星区第一中学电话13322224444张老师
用户解析json后可是实现自动填写地址的效果.丢去手动选择省市区的步骤.大大提高处理效率. z
本次改造原因和利弊性分析:
改造的原因,可能是因为:
一.
原来明文方式,容易被网络抓包获取到电商软件取号整个链路的明文信息导致数据泄露
二.
也可能是阿里为了在获取面单号的时候,快照一个交易的当前信息,然后在获取到单号或者是打印了以后,订单有修改的话,对打印数据进行一个校验(我没测试是不是订单锁)
但是这个订单锁概念实现起来其实没有这么简单,1是没有办法保证ISV上传的数据是否是真实数据.2是如果菜鸟想给大家传递一个订单锁的概念的话,不需要用这种方式,isv应该自己实现.3多数的ISV处理逻辑的顺序可能都不一样,如果打单和发货时间间隔很长,万一订单有修改了.单子也打出来了.造成浪费.虽然错的包裹发不出去了.但是大大提高了工作人员的工作量.
要说有利的地方,我除了觉得结构组织比较简明了以外,其他没有发现.倒是问题发现不少.
一
无效的加密数据,很多人都遇到过.网络原因会导致这个问题,重启组件有的可以好.有的就不行.可能是因为组件不是最新版本.还有就是就算组件是最新版本了.也不行,因为最新版本的组件和最新可用版本的组件 是一个编号 0.4.7.6. 所以如果你是0.4.7.6也有这个问题的话,你需要重新下载一个0.4.7.6的安装一下. 也就是说虽然版本号看着一样 但是实际上 他们已经更新了功能在新安装包里面但是没有发布版本.
二
京东又来凑热闹,也许是京东为了不让ISV把京东的订单信息在获取单号的时候给淘宝发过去.所以,他们就发布了云打印组件.
本来,很多给京东提供服务的ISV,是通过修改菜鸟电子面单标准模板的一些信息,或者是自绘模板来打印的.这样加密了以后,不能自绘了.就不方便做别的平台的订单处理了.
三
贴标机不方便用了.除了贴标机,有很多用户反应也需要使用三段码,大头笔等信息.虽然我不理解他们到底要这个有毛线用.但是!
真到用到的时候,也是不方便很多.倒也不是没有办法,比如:
使用ZanPrinter等虚拟打印机 输出图片形式的面单图
使用菜鸟云打印组件本身的预览功能可以生成Pdf和图片,可以进行进一步的操作.需要提取三段码的,可以读取pdf文件来获取
使用xps文件打印机,打印成xps文件后,读取xps的文件,类似读pdf的路子,也是能获取到一些信息.
综上所述,如果只是为了订单锁或者是为了信息安全传输,
额~ 你们自己理解吧