中国邮政国内小包服务订单规范详解.docx

密级：协议公布文献类别：技术规范中国邮政国内小包综合服务平台（订单系统）上游客户系统原则接口规范版本号：V1.0.0文档编号：YT-NPP-API-Oi编制单位：国内小包项目组编制人,黄春凤编制日期：2023年3月2日审核人，徐黎春审核日期，2023年3月3日批准人：李传波同意日期：2023年5月8日©Copyright2023-2023,HLJPostYiTongInfo-netCo.,Ltd.:086-变更历史日期变更描述变更者2023-3-2新建黄春凤2023-11-17增长重量字段1 概述错误!未定义书签。1.1 文档目的错误!未定义书签。1.2 技术支持错误!未定义书签。3参数、安全及数据完整性错误!未定义书签。2.1 参数定义错误!未定义书签。2.1.1 上游客户系统发送给中国邮政的参数错误!未定义书签。2.1.2 中国邮政发送给上游客户系统的参数错误!未定义书签。2.1.3 消息格式错误!未定义书签。2.2 安全及数据完整性错误!未定义书签。2.3 数据发送和接受处理流程错误!未定义书签。2.4 描述错误!未定义书签。3.1订单接口错误!未定义书签。字段含义错误!未定义书签。祈求格式错误!未定义书签。参数描述错误!未定义书签。返回格式错误!未定义书签。补充信息错误!未定义书签。2.5 2订单信息更新接口错误!未定义书签。字段含义错误!未定义书签。祈求格式错误!未定义书签。参数描述错误!未定义书签。3.2.4补充信息错误!未定义书签。4系统交互处理流程错误!未定义书签。4.1 流程图错误!未定义书签。4.2 格式错误!未定义书签。4.2.1 接口反馈成果错误!未定义书签。4.3 补充信息错误!未定义书签。4.4 业务错误信息错误!未定义书签。4.5 系统错误信息错误!未定义书签。5其他问题和注意事项错误!未定义书签。1概述1.1 文档目的本文档重要规范中国邮政国内小包综合服务平台与上游客户（如电商客户）系统的数据接口。1.2 技术支持本接口开发由黑龙江邮政易通信息网络有限责任企业提供支持，如有疑问请联络易通企业。3参数、安全及数据完整性2.1 参数定义2.1.1 上游客户系统发送给中国邮政的参数参数名称用途logistics_interface消息内容data_digest消息签名msg_type消息类型（无需辨别大小写）OcCompanyId电商标识，如“TA0BA0”（无需辨别大小写）2.1.2 中国邮政发送给上游客户系统的参数参数名称用途logistics_interface消息内容Iogistic_provider_idTP编号msg_type消息类型data_digest消息正文口勺摘要msg_type的值固定:属性值阐明默认消息格式Ordercreate创立订单XMLupdate订单更新（更新面单号、取消订单、接单、不接单、不揽收）XML2.1.3 消息格式祈求和响应的消息格式将所有是XML2.2 安全及数据完整性1、以POST方式发送，祈求措施聆J编码格式：“application-form-urIencoded;Charset=GBK”；2、用“IogisticsJnterface”字段表达要发送BXML内容；3、用“data_digest”字段进行签名验证。签名使用MD5方式，对IOgiStics_interface的）内容进行签名。原理为：告知内容xml+parternID,然后进行MD5,转换为Base64字符串。详细解释如下:假设xm内容为：<RequestOrder><RequestOrder>,Partnered为123456那么要签名的内容为<RequestOrder></ReqUeStorder>123456,通过md5和base64后的内容就为LghTkEnISD2tbQ3fsIBRcBg=,措施如下：MessageDigestmd5=MessageDigest.getlnstance(,MD5,*);BASE64Encoderbase64en=newBASE64Encoder();Ret=base64en.encode(md5.digest(str+artnered).getBytes("GBKu)；然后需要对Xml内容(<RequestOrderX/ReqUeStorder>)进行URL编码(字符集为GBK),为：%3Corder%3E%3C%2Forder%3E同样需要对签名口勺字符串进行URL编码，LghTkEnISD2tbQ3fSlBRcBg二的内容为：1.ghTkEmsD2tbQ3fsIBRcBg%3D%3D最终要发送的数据为：Iogistics_interface=%3Corder%3E%3C%2Forder%3E&data_digest=1.ghTkEmsD2tbQ3fslBRcBg%3D%3Dftmsgtype=?4、收到消息后，一定要验证数据与否完整及对的；5、传播通道安全(s),目前不规定实现。6、内容不对的？请检查字符集与否为GBK；所有的参数都是通过URL编码传送的，符合协议，注意客户端与否解码对的，有些控件已经自带URL解码功能，请开发人员注意。2.3 数据发送和接受处理流程数据发送流程：数字签名->发送；数据接受流程：接受-数字签名校验-处理;3接口描述3.1订单接口3.1.1字段含义字段名含义类型向度与否为空ecCompanyld电商标识（如：TAOBAO）String64NIogisticProviderID物流企业IDString64NCuslomerId客户标识String64YtxLogisticID物流订单号String64NtradeNo业务交易号（新业务类型待定I252国内小包）String64YmailNo物流运单号String64NOrderType订单类型（O-COD1一般订单3-退货单）intNServiceType服务类型（0-自己联络I-在线下单（上门揽收）4-限时物流8-快捷COD16-快递保障）longNname顾客姓名String32NpostCode顾客String6Nphone顾客，包括区号、号码及分机号，中间用分隔；String32Ymobile顾客移动，和两者必需提供一种String32Yprov顾客所在省String32Ncity顾客所在市县（区），市区中间用分隔；注意有些市下面是没有区String32Naddress顾客详细地址String256NSendStartTime物流企业上门取货时间段，通过"yyyy-MM-ddHH:mm:ss”格式化，本文中所有时间格式相似。timestampYSendEndTimetimestampYgoodsValue商品金额，包括优惠和运费，但无服务费longNitemName商品名称String256Nnumber商品数量intNitemValue商品单价（单位：分两位小数）longNspecial商品类型（保留字段,临时不用）intYremark备注String512YIotalServiceFee总服务费COD：（单位：分）longYbuyServiceFee买家服务费COD：（单位：分）longYCodSplitFee物流企业分润COD：（单位：分）longYweight商品重量（单位：克）longN3.1.2祈求格式XML格式:<RequestOrder><!一订单基本信息一>CecCompanyId>TAOBAO<ecCompanyId><logisticProviderID>POSTB<1ogisticProviderID><customerld>ab3ed2a2f0ff4d0b2bf5e<customerld><txLogisticID>LP09<txLogisticID><tradeNo>5709</tradeNo><mailNo><mailNo><totalServiceFee>3200<totalServiceFee><codSplitFee>2023<codSplitFee><buyServiceFee>1000<buyServiceFee><orderType>l<orderType><serviceType>O</serviceType><!一发货方信息一><sender><name>张三<name><postCode>310013<postCode><phone></phone><mobile><mobile><prov>浙江<prov><city>杭州，西湖区<city><address华星科技大厦9层<address><!一收货方信息一><receiver><name>李四<name><postCode>100000<postCode><phone></phone><mobile><mobile><prov>北京<prov><city>北京市<city><address>华星科技大厦9层"address<receiver>Q一物流企业上门取货时间段一><sendStartTime>2023-08-2408:00:00<sendStartTime><sendEndTime>2023-08-2412:00:00<sendEndTime><!商品信息一><goodsValue>1900<goodsValue><items><item><itemName>NokiaN73<itemName><number>2</number><itemValue>2<itemValue><item><item><itemName>NokiaN72<itemName><number>K/number><itemValue>2<itemValue><item><items><special>O<special><remark>易碎品</remark><weight>10</weight><RequestOrder>3.1.3 参数描述订单创立信息由电商物流平台发送给中国邮政，电商物流平台以PoST方式发送消息，参数格式如下：用途参数名称Iogisticsinterface4. 1.2节描述日勺XML字符串datadigestIogiStiCSinterfaC。的MD5 签名msgtype固定“ORDERCREATE" （不辨别大小写）ecCompanyld固定为“TAOBAO"（不辨别大小写）3.1.4 返回格式返回原则的系统交互格式，详情见4系统交互处理流程3.1.5 补充信息1、物流订单号在上游客户系统中要具有唯一性2、卖家发货后，电商物流平台实时发送订单到邮政物流企业，这是系统交互，跟背面的业务处理是分开的；3.2订单信息更新接口3.2.1 字段含义字段名含义类型长度与否为空IogisticProviderID物流企业编号String64NecCompanyld电商标识；如淘宝的消息，此字段填写为“TAOBAO”；String64YfieldList(fieldl.20)txLogisticID物流平台的物流号（不能为空）String64NfieldName可更新字段：1、 mailNo；2、 weight；3、 statusString64NfieldValue字段新值String64Nremark取消订单、不接单、不揽收时，此字段用于填写原因String215Y注：可以同步更新多笔订单，但最多不超过20个;status字段可选值:名称阐明WITHDRAW取消订单ACCEPT接单成功UNACCEPT接单失败NOT_SEND揽收失败3.2.2 祈求格式XML格式:<UpdateInfo><logisticProviderID>POSTB<logisticProviderID><ecCompanyId>TAOBAO</ecCompanyId><fieldList><field><txLogisticID>LP09<txLogisticID><fieldNamc>mailNo<fieldName><fieldValue>32323232<fieldValue><remark></remark><field><field><txLogisticID>LP09<txLogisticID><fieldName>weight<fieldName><fieldValue>10<fieldValue><remark></remark><field><field><txLogisticID>LP09<txLogisticID><fieldName>status<fieldName><fieldValue>ACCEPT<fieldValue><remark></remark><field><field><txLogisticID>LR23</txLogiSticID><fieldName>status<fieldName><fieldValue>WITHDRAW<fieldValue><remark>没货</remark><field><field><txLogisticID>LR56<txLogisticID><fieldName>status<fieldName><fieldValue>ACCEPT<fieldValue><remark></remark><field><field><txLogisticID>LR56<txLogisticID><fieldNamc>mailNo<fieldName><fieldValue>45875213<fieldValue><remark></remark><field><field><txLogisticID>LR19<txLogisticID><fieldNamo>status</fieldName><fieldValue>UNACCEPT<fieldValue><remark>B04</remark><field><field><txLogisticID>LR29<txLogisticID><fieldName>status</fieldName><fieldValue>NOT.SEND<fieldValue><remark>不送了<remark><field><field><txLogisticID>LP42<txLogisticID><fieldName>status</fieldName><fieldValue>ACCEPT<fieldValue><remark><remark><field><field><txLogisticID>LP89<txLogisticID><fieldName>mailNo<fieldName><fieldValue>87561245<fieldValue><remark><remark><field><fieldList><UpdateTnfo>注：1、面单号更新，可以是电商物流平台发送给邮政物流企业，也可以是邮政物流企业发送给电商物流平台。2、更新重量信息，由邮政物流企业发送给电商物流平台；3、取消订单消息由电商物流平台发送给邮政物流企业；4、接单成功、接单失败、揽收失败消息由邮政物流企业发送给电商物流平台，接单失败和揽收失败需要在remark中填写原因；5、可以一次性更新同一笔订单的多种字段，可以一次性更新多笔订单的同一字段，还可以一次性更新多笔订单的多种字段。但"fieldList"中"field”最多不超过20,至少不少于L3.2.2.1更多祈求格式举例示例1：淘宝要更新LP67和LP65日勺面单号；下面消息由淘宝发送给邮政:<UpdateInfo><logistIcProviderID>POSTB<logiSticProviderID><ecCompanyId>TOBAO<ecCompanyId><fieldList><field><txLogisticID>LP67<txLogisticID><fieldName>mailNo<fieldName><fieldValue><fieldValue><remark></remark><field><field><txLogisticID>LP65<txLogisticID><fieldName>mailNo<fieldName><fieldValue><fieldValue><remark></remark><field><fieldList><UpdateInfo>示例2：邮政要更新LP03和LP63H勺面单号；下面消息由邮政发送给淘宝:<logisticProviderID>POSTB<logisticProviderID><ecCompanyId>TA0BA0<ecCompanyId><fieldList><field><txLogisticID>LP03<txLogisticID><fieldName>mailNo<fieldName><fieldValue><fieldValue><remark></remark><field><field><txLogisticID>LP63<txLogisticID><fieldName>mailNo<fieldName><fieldValue><fieldValue><remark></remark><field><fieldList><UpdateInfo>示例3：邮政要更新LP71的面单号，更新LP40的重量，并且LP69接单成功；下面消息由邮政发送给淘宝：<UpdateInfo><logisticProvider1D>POSTB</IogisticProviderID><ecCompanyId>TAOBAO<ecCompanyId><fieldList><field><txLogisticID>LP03<txLogisticlD><fieldName>mailNo<fieldName><fieldValue><fieldValue><remark></remark><field><field><txLogisticID>LP40<txLogisticID><fieldName>weight<fieldName><fieldValue>16<fieldValue><remark></remark><field><field><txLogisticID>LP69<txLogisticID><fieldName>status<fieldName><fieldValue>ACCEPT<fieldValue><remark></remark><field><fieldList><UpdateInfo>示例4：淘宝要取消订单LP92,如下消息由淘宝发送给邮政：<UpdateInfo><logisticProviderID>POSTB<logistIcProvider1D><ecCompanyId>TAOBAO</ecCompanyId><fieldList><field><txLogisticID>LP92<txLogisticID><fieldName>status<fieldName><fieldValue>WITHDRW<fieldValue><remark>没货了</remark><field><fieldList><UpdateInfo>示例5：邮政订单LP74接单失败，订单LP39揽收失败，如下消息由邮政发送给淘宝:<Updatelnfo><logisticProviderID>POSTB<logisticProviderID><ccCompanyId>TAOBAO</ecCompanyId><fieldList><field><txLogisticID>LP74<txLogisticID><fieldName>status</fieldName><fieldValue>UNACCEPT<fieldValue><remark>S02<remark><field><field><txLogisticID>LP39<txLogisticID><fieldName>status</fieldName><fieldValue>NOTSEND<fieldValue><remark>B04<remark><field><fieldList><UpdateInfo>3.2.3参数描述3.2.3.1电商物流平台发送给物流企业参数描述参数名称用途logistics_interface4.2.2节描述的XML字符串datadigestIOgiStics_interface的MD5签名msg_type固定为“UPDATE"（不辨别大小写）GcCompanyId固定为“TAOBAO"（不辨别大小写）3.2.3.2物流企业发送给电商物流平台的参数描述参数名称用途logistics_interface4.2.2节描述的XML字符串Iogistic_provider_idTP编号msg_type固定为“UPDATE"（不辨别大小写）datadigestIOgiStics_interfaceH勺MD5签名3.2.3.3返回格式返回原则的系统交互格式，详情见4系统交互处理流程订单更新成果。3.2.4补充信息1、顾客下单后在物流企业返回揽收消息前都可以进行取消操作；2、物流状态更新规定严格按照主流程图发送，否则返回对应的业务错误信息;4系统交互处理流程4.1 流程图接收方后台处理：4.2 格式4.1.1接口反馈成果XML格式成功：<responses><logisticProviderID>POSTB<IogisticProviderID><responseltems><response><txLogisticID>LP09000<txLogisticID><success>true</success><response><responseltems><responses>XML格式失败：<responses><1ogiSticProviderID>POSTB</logisticProviderID><responseltems><response><txLogisticID>LP09000<txLogisticID><success>false</success><reason>S01<reason><response><responseltems><responses>4.3 补充信息1、不管是电商物流平台发送订单给中国邮政还是邮政物流企业发送状态告知给电商物流平台都是次系统交互H勺过程，需要有发送和响应。2、所谓发送就是发送方发送数据。3、所谓响应就是接受方告诉发送方数据与否接受成功。4、系统的应答是同步的，既数据发送方发送数据后接受方立即返回在输出流里，而业务的返回是后续状态告知到物流平台接口上日勺，必须辨别开。5、返回失败的消息，会返回对应的系统错误信息。4.4 业务错误信息标识阐明B99非法的物流订单号BOl不能进行操作，目前状态是：等待确认B02不能进行操作，目前状态是：接单B03不能进行操作，目前状态是：不接单B04不能进行操作，目前状态是：揽收成功B05不能进行操作，目前状态是：揽收失败B06不能进行操作，目前状态是：签收成功B07不能进行操作，目前状态是：签收失败B08不能进行操作，目前状态是：订单已取消B09不能进行操作，运单号为空BlO不能进行操作，签收信息为空（包括运单号、签收姓名、签收时间不能为空）4.5 系统错误信息标识阐明SOl非法的XML格式S02非法的数字签名S03非法的物流企业S04非法的告知类型S05非法的告知内空S07系统异常，请重试S08非法丛J电商平台5其他问题和注意事项1.各接口中定义的字段，非可变部分尽量不要校验大小写；字符串长度在文档定义的长度基础上，再预留一定的!缓存区间。结束