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

1、文件类别：技术规范文件类别：技术规范 密级：协议发布密级：协议发布中国邮政国内小包综合服务平台（订单系统）上游客户系统标准接口规范版本号：版本号：V1.0.0文档编号：文档编号：YT-NPP-API-01YT-NPP-API-01编制单位：编制单位：国内小包项目组国内小包项目组编编 制制 人：人： 黄春凤黄春凤编制日期：编制日期：20142014 年年 3 3 月月 2 2 日日审审 核核 人：人：徐黎春徐黎春审核日期：审核日期：20142014 年年 3 3 月月 3 3 日日中国邮政国内小包综合服务平台订单接口规范 v1.0.0 2 / 23批批 准准 人：人：李传波李传波批准日期：批准日

2、期：20142014 年年 5 5 月月 8 8 日日 Copyright 2001-2014, HLJ Post YiTong Info-net Co.,Ltd.网址：http:/www.e- 电话：086址：中国哈尔滨市南岗区西大直街 133 号 传真：086国邮政国内小包综合服务平台订单接口规范 v1.0.0 3 / 23变更历史变更历史日期日期变更描述变更描述变更者变更者2014-3-2新建黄春凤2015-11-17增加重量字段中国邮政国内小包综合服务平台订单接口规范 v1.0.0 4 / 23目目 录录1概述概述.41.1

3、文档目的.41.2 技术支持.43 参数、安全及数据完整性参数、安全及数据完整性.42.1 参数定义.42.1.1 上游客户系统发送给中国邮政的参数.42.1.2 中国邮政发送给上游客户系统的参数.52.1.3 消息格式.52.2 安全及数据完整性.52.3 数据发送和接收处理流程.63 接口描述接口描述.73.1 订单接口.73.1.1 字段含义.73.1.2 请求格式.83.1.3 参数描述.103.1.4 返回格式.103.1.5 补充信息.103.2 订单信息更新接口.113.2.1 字段含义.113.2.2 请求格式.123.2.3 参数描述.183.2.4 补充信息.184 系统交

4、互处理流程系统交互处理流程.194.1 流程图.194.2 格式.194.1.1 接口反馈结果.194.3 补充信息.204.4 业务错误信息.214.5 系统错误信息.215 其它问题和注意事项其它问题和注意事项.22中国邮政国内小包综合服务平台订单接口规范 v1.0.0 5 / 231 1概述概述1.1 文档目的文档目的本文档主要规范中国邮政国内小包综合服务平台与上游客户（如电商客户）系统的数据接口。1.2 技术支持技术支持本接口开发由黑龙江邮政易通信息网络有限责任公司提供支持，如有疑问请联系易通公司。3 3 参数、安全及数据完整性参数、安全及数据完整性 2.1 参数定义参数定义 2.1.

5、1 上游客户系统发送给中国邮政的参数上游客户系统发送给中国邮政的参数 参数名称 用途 logistics_interface 消息内容 data_digest 消息签名 msg_type 消息类型 （无需区分大小写） ecCompanyId 电商标识，如“TAOBAO” （无需区分大小写） 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 6 / 232.1.2 中国邮政发送给上游客户系统的参数中国邮政发送给上游客户系统的参数 参数名称 用途 logistics_interface 消息内容 logistic_provider_id TP编号 msg_type 消息类型 data_dig

6、est 消息正文的摘要 msg_type的值固定： 属性值 说明 默认消息格式 ORDERCREATE 创建订单 XML UPDATE 订单更新（更新面单号、取消订单、接单、不接单、不揽收） XML 2.1.3 消息格式消息格式 请求和响应的消息格式将全部是XML2.2 安全及数据完整性安全及数据完整性 1、 以HTTP POST方式发送，请求方法的编码格式：“application/x-www-form-urlencoded; charset=GBK” ； 2、 用“logistics_interface”字段表示要发送的XML内容； 3、 用“data_digest”字段进行签名验证。签名

7、使用MD5方式，对logistics_interface的内容进行签名。原理为：通知内容xml+parternID，然后进行MD5，转换为Base64字符串。 详细解释如下： 假设xml内容为： ， partnered为123456 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 7 / 23 那么要签名的内容为123456，经过md5和base64后的内容就为LghTkEmsD2tbQ3fsIBRcBg= ,方法如下：MessageDigest md5 = MessageDigest.getInstance(MD5);BASE64Encoder base64en = new BASE

8、64Encoder();Ret=base64en.encode(md5.digest(str+partnered).getBytes(GBK); 然后需要对xml内容（）进行URL编码（字符集为GBK） ，为：%3Corder%3E%3C%2Forder%3E 同样需要对签名的字符串进行URL编码，LghTkEmsD2tbQ3fsIBRcBg=的内容为：LghTkEmsD2tbQ3fsIBRcBg%3D%3D 最终要发送的数据为：logistics_interface=%3Corder%3E%3C%2Forder%3E&data_digest= LghTkEmsD2tbQ3fsIBRc

9、Bg%3D%3D&msg_type =? 4、收到消息后，一定要验证数据是否完整及正确； 5、传输通道安全（https） ，目前不要求实现。 6、内容不正确？请检查字符集是否为GBK；所有的参数都是通过URL编码传送的，符合HTTP协议，注意客户端是否解码正确，有些控件已经自带URL解码功能，请开发人员注意。 2.3 数据发送和接收处理流程数据发送和接收处理流程 数据发送流程：数字签名- 发送； 数据接收流程：接收- 数字签名校验-处理； 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 8 / 233 3 接口描述接口描述3.1 订单接口订单接口3.1.1 字段含义字段含义字段

10、名含义类型长度是否为空ecCompanyId电商标识（如：TAOBAO）String64NlogisticProviderID物流公司 IDString64NcustomerId客户标识String64YtxLogisticID物流订单号String64NtradeNo业务交易号（新业务类型待定：业务交易号（新业务类型待定：252国内小包）国内小包）String64YmailNo物流运单号String64NorderType订单类型(0-COD 1-普通订单 3 - 退货单)intNserviceType服务类型(0-自己联系 1-在线下单（上门揽收）4-限时物流 8-快捷COD 16-快递保

11、障)longNname用户姓名String32NpostCode用户邮编String6Nphone用户电话，包括区号、电话号码及分机号，中间用“-”分隔；String32Ymobile用户移动电话, 手机和电话两者必需提供一个String32Yprov用户所在省String32Ncity用户所在市县（区） ，市区中间用“,”分隔；注意有些市下面是没有String32N中国邮政国内小包综合服务平台订单接口规范 v1.0.0 9 / 23区address用户详细地址String256NsendStartTimetimestampYsendEndTime物流公司上门取货时间段，通过“yyyy-MM-

12、dd HH:mm:ss”格式化，本文中所有时间格式相同。timestampYgoodsValue商品金额，包括优惠和运费，但无服务费longNitemName商品名称String256Nnumber商品数量intNitemValue商品单价（单位：分 两位小数）longNspecial商品类型（保留字段，暂时不用）intYremark备注String512YtotalServiceFee总服务费COD：（单位：分）longYbuyServiceFee买家服务费COD ：（单位：分）longYcodSplitFee物流公司分润COD ：（单位：分） longYweight商品重量（单位：克）lo

13、ngN3.1.2 请求格式请求格式XML格式： TAOBAO POSTB a92266073246b3ed2a2f0ff4d0b2bf5e LP07082300225709 2007082300225709 124579546621 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 10 / 233200 2000 1000 1 0 张三 310013 231234134浙江 杭州,西湖区 华星科技大厦9层 李四 100000 231234134北京 北京市 华星科技大厦9层 2005-08-24 08:00:00 2005-08-24

14、 12:00:00 1900 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 11 / 23 Nokia N73 2 2 Nokia N72 1 2 0 易碎品 10 3.1.3 参数描述参数描述 订单创建信息由电商物流平台发送给中国邮政，电商物流平台以HTTP POST方式发送消息，参数格式如下：参数名称 用途 logistics_interface 4.1.2节描述的XML字符串 data_digest logistics_interface的MD5签名 msg_type 固定“ORDERCREATE” (不区分大小写) ecCompanyId 固定为“TAOBAO”(不区分大小写

15、) 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 12 / 233.1.4 返回格式返回格式返回标准的系统交互格式，详情见4 系统交互处理流程3.1.5 补充信息补充信息1、物流订单号在上游客户系统中要具有唯一性 2、卖家发货后，电商物流平台实时发送订单到邮政物流公司，这是系统交互，跟后面的业务处理是分开的；3.23.2 订单信息更新接口订单信息更新接口 3.2.1 字段含义字段含义字段名含义类型长度是否为空logisticProviderID物流公司编号String64NecCompanyId电商标识；如淘宝的消息，此字段填写为“TAOBAO” ；String64YtxLogist

16、icID物流平台的物流号（不能为空）String64NfieldName可更新字段：1、mailNo；2、weight；3、statusString64NfieldValue字段新值String64NfieldList(field1.20)remark取消订单、不接单、不揽收时，此字段用于填写原因String215Y注：可以同时更新多笔订单，但最多不超过20个； status 字段可选值：中国邮政国内小包综合服务平台订单接口规范 v1.0.0 13 / 23名称 说明 WITHDRAW 取消订单 ACCEPT 接单成功 UNACCEPT 接单失败 NOT_SEND 揽收失败 3.2.2 请求格

17、式请求格式XML格式： POSTB TAOBAO LP07082300225709 mailNo 32323232 LP07082300225709 weight 10 LP07082300225709 status ACCEPT 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 14 / 23 LR07082300224123 status WITHDRAW 没货 LR07082300227456 status ACCEPT LR07082300227456 mailNo 45875213 LR07082300224719 status UNACCEPT B04 LR070823002

18、28529 status NOT_SEND 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 15 / 23不送了 LP07082300789542 status ACCEPT LP07082300745289 mailNo 87561245 注： 1、面单号更新，可以是电商物流平台发送给邮政物流公司，也可以是邮政物流公司发送给电商物流平台。 2、更新重量信息，由邮政物流公司发送给电商物流平台； 3、取消订单消息由电商物流平台发送给邮政物流公司； 4、接单成功、接单失败、揽收失败消息由邮政物流公司发送给电商物流平台，接单失败和揽收失败需要在remark中填写原因； 5、可以一次性更新同一

19、笔订单的多个字段，可以一次性更新多笔订单的同一字段，还可以一次性更新多笔订单的多个字段。但” fieldList”中” field”最多不超过 20，最少不少于 1。 更多请求格式举例更多请求格式举例 示例1 1：淘宝要更新LP07082300712367和LP07082300723465的面单号；下面消息由淘宝发送中国邮政国内小包综合服务平台订单接口规范 v1.0.0 16 / 23给邮政： POSTB TAOBAO LP07082300712367 mailNo 123457890 LP07082300723465 mailNo 234670641 示例2 2

20、：邮政要更新LP07082300711603和LP07082300723763的面单号；下面消息由邮政发送给淘宝： POSTB TAOBAO LP07082300711603 mailNo 237543899 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 17 / 23 LP07082300723763 mailNo 2348065433 示例3 3：邮政要更新LP07082300725671的面单号，更新LP07082300727340的重量，并且LP07082300712569接单成功；下面消息由邮政发送给淘宝： POSTB TAOBAO LP07082300711603 mai

21、lNo 237543899 LP07082300727340 weight 16 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 18 / 23 LP07082300712569 status ACCEPT 示例4 4：淘宝要取消订单LP07082300716792，以下消息由淘宝发送给邮政： POSTB TAOBAO LP07082300716792 status WITHDRAW 没货了 示例5 5：邮政订单LP07082300123674接单失败，订单LP07082300456239揽收失败，以下消息由邮政发送给淘宝： POSTB TAOBAO LP07082300123674

22、中国邮政国内小包综合服务平台订单接口规范 v1.0.0 19 / 23status UNACCEPT S02 LP07082300456239 status NOT_SEND B04 3.2.3 参数描述参数描述 电商物流平台发送给物流公司参数描述电商物流平台发送给物流公司参数描述 参数名称 用途 logistics_interface 4.2.2节描述的XML字符串 data_digest logistics_interface的MD5签名 msg_type 固定为“UPDATE” (不区分大小写) ecCompanyId 固定为“TAOBAO”(不区分大小写)

23、 物流公司发送给电商物流平台的参数描述物流公司发送给电商物流平台的参数描述 参数名称 用途 logistics_interface 4.2.2节描述的XML字符串 logistic_provider_id TP编号 msg_type 固定为“UPDATE” (不区分大小写) data_digest logistics_interface的MD5签名 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 20 / 返回格式返回格式 返回标准的系统交互格式，详情见4 系统交互处理流程订单更新结果。 3.2.4 补充信息补充信息 1、用户下单后在物流公司返回揽收消息前都可以进行取消操作； 2、物流状态更新要求严格按照主流程图发送，否则返回相应的业务错误信息； 中国邮政国内小包综合服务平台订单接口规范 v1.0.0 21 / 234 4 系统交互处理流程系统交互处理流程4.1 流程图流程图4.2 格式格式4.1.1 接口反馈结果接口反馈结果 XML