中国邮政国内小包综合服务平台订单接口规范

1、中国邮政国内小包综合服务平台订单接口规范vl.0.0密级：协议发布文件类别：技术规范中国邮政国内小包综合服务平台（订单系统）上游客户系统标准接口规范版本号：V1.0.0文档编号：YT-NPP-API-01编制单位：国内小包项目组编制人：更春凤编制日期：2014年3月2日审核人：徐黎春审核日期：2014年3月3日批准人：李传波批准日期：2014年5月8日?Copyright2001-2014,HLJPostYiTongInfo-netCo.,Ltd.网址：http:/www.e-地址：中国哈尔滨市南岗区西大直街133号传真：086更历史日期变更描述艾更者2014-3

2、-2新建更春凤2015-11-17增加重量字段22 / 22目录1 概述41.1 文档目的41.2 技术支持43参数、安全及数据完整性42.1 参数定义42.1.1 上游客户系统发送给中国邮政的参数42.1.2 中国邮政发送给上游客户系统的参数52.1.3 消息格式52.2 安全及数据完整性52.3 数据发送和接U处理流程63接口描述73.1 订单接口73.1.1 字段含义73.1.2 请求格式83.1.3 参数描述103.1.4 返回格式103.1.5 补充信息113.2 订单信息更新接口113.2.1 字段含义113.2.2 请求格式123.2.3 参数描述183.2.4 补充信息194系

3、统交互处理流程194.1 流程图194.2 格式204.2.1 接口反馈结果204.3 补充信息214.4 业务错误信息214.5 系统错误信息215其它问题和注意事项221概述1.1 文档目的本文档主要规范中国邮政国内小包综合服务平台与上游客户（如电商客户）系统的数据接口。1.2 技术支持本接口开发由黑龙江邮政易通信息网络有限责任公司提供支持，如有疑问请联系易通公司。3参数、安全及数据完整性2.1参数定义2.1.1 上游客户系统发送给中国邮政的参数参数名称用途logistics_interface消息内容data_digest消息签名msg_type消息类型（无需区分大小写）ecCompan

4、yld电商标识，如“TAOBAO（无需区分大小写）2.1.2 中国邮政发送给上游客户系统的参数参数名称用途logistics_interface消息内容logistic_provider_idT喻号msg_type消息类型data_digest消息正文的摘要msg_type的值固定:属性值说明默认消息格式ORDERCREATE创建订单XMLUPDATE订单更新（更新囿单号、取消订单、接单、不接单、不揽收）XML2.1.3 消息格式请求和响应的消息格式将全部是XML2.2安全及数据完整性1、以HTTPPOS昉式发送，请求方法的编码格式：“application/x-www-form-urlenc

5、oded;charset=GBK”;2、用“logistics_interface”字段表示要发送的XM呐容；3、用"data_digest”字段进行签名验证。签名使用MD昉式，对logistics_interface的内容进行签名。原理为：通知内容xml+parternID,然后进行MD5转换为Base64字符串。详细解释如下：假设xml内容为：<RequestOrder></RequestOrder>,partnered为123456那么要签名的内容为<RequestOrder></RequestOrder>123456,经过md5

6、口base64后的内容就为LghTkEmsD2tbQ3fsIBRcBg=,方法如下：MessageDigestmd5=MessageDigest.getInstance("MD5");BASE64Encoderbase64en=newBASE64Encoder();Ret=base64en.encode(md5.digest(str+partnered).getBytes("GBK");然后需要对xml内容(<RequestOrder></RequestOrder>)进行UR编码(字符集为GBK,为：3Corder%3E%3C%2

7、Forder%3E同样需要对签名的字符串进行UR编码，LghTkEmsD2tbQ3fsIBRcBg=的内容为：LghTkEmsD2tbQ3fsIBRcBg%3D%3D最终要发送的数据为：logistics_interface=%3Corder%3E%3C%2Forder%3E&data_digest=LghTkEmsD2tbQ3fsIBRcBg%3D%3D&msg_type=?4、收到消息后，一定要验证数据是否完整及正确；5、传输通道安全(https),目前不要求实现。6、内容不正确？请检查字符集是否为GBK所有的参数都是通过UR编码传送白1符合HTTP协议，注意客户端是否解码

8、正确，有些控件已经自带UR1M码功能，请开发人员注意。2.3数据发送和接收处理流程数据发送流程：数字签名->发送；数据接收流程：接收->数字签名校验->处理;3接口描述3.1 订单接口3.1.1 字段含义字段名含义长度是否为空ecCompanyld电商标识（如：TAOBAO）String64NlogisticProviderlD物流公司IDString64Ncustomerld客户标识String64YtxLogisticID物流订单号String64NtradeNo业务交易号（新业务类型待定：252国内小包）String64YmailNo物流运单号String64Norde

9、rType订单类型（0-COD1-普通订单3-退货单）intNserviceType服务类型（0-自己联系1-在线下单（上门揽收）4-限时物流8-快捷COD16-快递保障）longNname用户姓名String32NpostCode用户邮编String6Nphone用户电话，包括区号、电话号码及分机号，中间用“-”分隔；String32Ymobile用户移动电话，手机和电话网若必需提供一个String32Yprov用户所在省String32Ncity用户所在市县（区），市区中间用“：分隔；注意有些市下面是没有区String32Naddress用户详细地址String256NsendStartT

10、ime物流公司上门取货时间段，通过yyyy-MM-ddHH:mm:ss”格式化，本文中所有时间格式相同。timestampYsendEndTimetimestampYgoodsValue商品金额，包括优惠和运费，但无服务费longNitemName商品名称String256Nnumber商品数量intNitemValue商品单价（单位：分两位小数）longNspecial商品类型（保留字段,暂时不用）intYremark备注String512YtotalServiceFee总服务费COD:（单位：分）longYbuyServiceFee买家服务费COD:（单位：分）longYcodSplitF

11、ee物流公司分润COD:（单位：分）longYweight商品重量（单位：克）longN3.1.2请求格式XM胳式：<RequestOrder><!一订单基本信息-><ecCompanyId>TAOBAO</ecCompanyId><logisticProviderID>POSTB</logisticProviderID><customerId>a92266073246b3ed2a2f0ff4d0b2bf5eVcustomerId><txLogisticID>LP07082300225709&

12、lt;/txLogisticID><tradeNo>2007082300225709</tradeNo><mailNo>124579546621</mailNo><totalServiceFee>3200</totalServiceFee><codSplitFee>2000</codSplitFee><buyServiceFee>1000</buyServiceFee><orderType>1</orderType><serviceType

13、>0</serviceType><!一发货方信息-><sender><name涨三</name><postCode>310013</postCode><phone>231234134</phone><mobile>lt;/mobile><prov>浙江</prov><city>杭州,西湖区</city><address>华星科技大厦9层</address></sende

14、r>< !-收货方信息-><receiver><name4四</name><postCode>100000</postCode><phone>231234134</phone><mobile>lt;/mobile><prov>北京</prov><city>北京市</city><address>华星科技大厦9层</address></receiver>< !-物流公司上门

15、取货时间段-><sendStartTime>2005-08-2408:00:00</sendStartTime><sendEndTime>2005-08-2412:00:00</sendEndTime>< !-商品信息-><goodsValue>1900</goodsValue><items><item><itemName>NokiaN73</itemName><number>2</number><itemValue>2&

16、lt;/itemValue></item><item><itemName>NokiaN72</itemName><number>1</number><itemValue>2</itemValue></item></items><special>0</special><remark>易碎品</remark>< weight>10</weight></RequestOrder>3.1.3 参

17、数描述电商物流平台以HTTP POST式发送消息,用途4.1.2节描述的XM字符串logistics_interface的 MD签名固定“ ORDERCREATE（不区分大小写）固定为“ TAOBAO （不区分大小写）订单创建信息由电商物流平台发送给中国邮政,参数格式如下：参数名称logistics_interfacedata_digestmsg_typeecCompanyld3.1.4 返回格式返回标准的系统交互格式，详情见4系统交互处理流程3.1.5 补充信息1、物流订单号在上游客户系统中要具有唯一性2、卖家发货后，电商物流平台实时发送订单到邮政物流公司，这是系统交互，跟后面的业务处理是分

18、开的；3.2订单信息更新接口3.2.1 字段含义字段名含义长度是否为空logisticProviderlD物流公司编号String64NecCompanyld电商标识；如淘宝的消息，此字段填写为“taobAO；String64YfieldList(field1.20)txLogisticID物流平台的物流号（不能为空）String64NfieldName可更新字段：1、mailNo；2、weight;3、statusString64NfieldValue字段新值String64Nremark取消订单、不接单、不揽收时，此字段用于填写原因String215Y注：可以同时更新多笔订单，但最多不超过

19、20个;status字段可选值:名称说明WITHDRAW取消订单ACCEPT接单成功UNACCEPT接单失败NOT_SEND揽收失败3.2.2 请求格式XM胳式：<UpdateInfo><logisticProviderID>POSTB</logisticProviderID><ecCompanyId>TAOBAO</ecCompanyId><fieldList><field><txLogisticID>LP07082300225709</txLogisticID><fieldNa

20、me>mailNo</fieldName><fieldValue>32323232</fieldValue><remark></remark></field><field><txLogisticID>LP07082300225709</txLogisticID><fieldName>weight</fieldName><fieldValue>10</fieldValue><remark></remark><

21、;/field><field><txLogisticID>LP07082300225709</txLogisticID><fieldName>status</fieldName><fieldValue>ACCEPT</fieldValue><remark></remark></field><field><txLogisticID>LR07082300224123</txLogisticID><fieldName>statu

22、s</fieldName><fieldValue>WITHDRAW</fieldValue><remark>没货</remark></field><field><txLogisticID>LR07082300227456</txLogisticID><fieldName>status</fieldName><fieldValue>ACCEPT</fieldValue><remark></remark></fie

23、ld><field><txLogisticID>LR07082300227456</txLogisticID><fieldName>mailNo</fieldName><fieldValue>45875213</fieldValue><remark></remark></field><field><txLogisticID>LR07082300224719</txLogisticID><fieldName>status&l

24、t;/fieldName><fieldValue>UNACCEPT</fieldValue><remark>B04</remark></field><field><txLogisticID>LR07082300228529</txLogisticID><fieldName>status</fieldName><fieldValue>NOT_SEND</fieldValue><remark>不送了</remark></

25、field><field><txLogisticID>LP07082300789542</txLogisticID><fieldName>status</fieldName><fieldValue>ACCEPT</fieldValue><remark></remark></field><field><txLogisticID>LP07082300745289</txLogisticID><fieldName>mailNo&

26、lt;/fieldName><fieldValue>87561245</fieldValue><remark></remark></field></fieldList></UpdateInfo>注：1、面单号更新，可以是电商物流平台发送给邮政物流公司，也可以是邮政物流公司发送给电商物流平台。2、更新重量信息，由邮政物流公司发送给电商物流平台；3、取消订单消息由电商物流平台发送给邮政物流公司；4、接单成功、接单失败、揽收失败消息由邮政物流公司发送给电商物流平台，接单失败和揽收失败需要在remark中填写原因

27、；5、可以一次性更新同一笔订单的多个字段，可以一次性更新多笔订单的同一字段，还可以一次性更新多笔订单的多个字段。但"fieldList"中"field”最多不超过20,最少不少于1。 更多请求格式举例示例1:淘宝要更新LP07082300712367和LP07082300723465的面单号；下面消息由淘宝发送给邮政：<UpdateInfo><logisticProviderID>POSTB</logisticProviderID><ecCompanyId>TAOBAO</ecCompanyId&

28、gt;<fieldList><field><txLogisticID>LP07082300712367</txLogisticID><fieldName>mailNo</fieldName><fieldValue>123457890</fieldValue><remark></remark></field><field><txLogisticID>LP07082300723465</txLogisticID><fieldN

29、ame>mailNo</fieldName><fieldValue>234670641</fieldValue><remark></remark></field></fieldList></UpdateInfo>示例2:邮政要更新LP07082300711603和LP07082300723763的面单号；下面消息由邮政发送给淘宝：<UpdateInfo><logisticProviderID>POSTB</logisticProviderID><ecC

30、ompanyId>TAOBAO</ecCompanyId><fieldList><field><txLogisticID>LP07082300711603</txLogisticID><fieldName>mailNo</fieldName><fieldValue>237543899</fieldValue><remark></remark></field><field><txLogisticID>LP0708230072

31、3763</txLogisticID><fieldName>mailNo</fieldName><fieldValue>2348065433</fieldValue><remark></remark></field></fieldList></UpdateInfo>示例3:邮政要更新LP07082300725671的面单号，更新LP07082300727340的重量，并且LP07082300712569接单成功；下面消息由邮政发送给淘宝：<UpdateInfo>&

32、lt;logisticProviderID>POSTB</logisticProviderID><ecCompanyId>TAOBAO</ecCompanyId><fieldList><field><txLogisticID>LP07082300711603</txLogisticID><fieldName>mailNo</fieldName><fieldValue>237543899</fieldValue><remark></remar

33、k></field><field><txLogisticID>LP07082300727340</txLogisticID><fieldName>weight</fieldName><fieldValue>16</fieldValue><remark></remark></field><field><txLogisticID>LP07082300712569</txLogisticID><fieldName>s

34、tatus</fieldName><fieldValue>ACCEPT</fieldValue><remark></remark></field></fieldList></UpdateInfo>示例4:淘宝要取消订单LP07082300716792,以下消息由淘宝发送给邮政：<UpdateInfo><logisticProviderID>POSTB</logisticProviderID><ecCompanyId>TAOBAO</ecCompa

35、nyId><fieldList><field><txLogisticID>LP07082300716792</txLogisticID><fieldName>status</fieldName><fieldValue>WITHDRAW</fieldValue><remark>没货了</remark></field></fieldList></UpdateInfo>示例5:邮政订单LP07082300123674接单失败，订单LP070

36、82300456239揽收失败，以下消息由邮政发送给淘宝：<UpdateInfo><logisticProviderID>POSTB</logisticProviderID><ecCompanyId>TAOBAO</ecCompanyId><fieldList><field><txLogisticID>LP07082300123674</txLogisticID><fieldName>status</fieldName><fieldValue>UNAC

37、CEPT</fieldValue><remark>S02</remark></field><field><txLogisticID>LP07082300456239</txLogisticID><fieldName>status</fieldName><fieldValue>NOT_SEND</fieldValue><remark>B04</remark></field></fieldList></Update

38、Info>3.2.3 参数描述 电商物流平台发送给物流公司参数描述参数名称用途logistics_interface4.2.2节描述的XM字符串data_digestlogistics_interface的MD醛名msg_type固定为"UPDATE（不区分大小写）ecCompanyId固定为“TAOBAO（/、区分大小写） 物流公司发送给电商物流平台的参数描述参数名称用途logistics_interface4.2.2节描述的XM字符串logistic_provider_id丁函号msg_type固定为“UPDATE（/、区分大小写）data_digestlogistics_interface的MD醛名 返回格式返回标准的系统交互格