快递鸟物流接口技术文档.docx

编号：时间：2021年x月x日书山有路勤为径，学海无涯苦作舟页码：第89页 共90页快递鸟接口(API)技术文档版本日期版本说明作者2014-12-013.0重新整理，根据功能分类，部分有调整杨文胜2014-01-113.1对接口的说明进行了注释，提高可读性杨汉汶2014-01-133.2新增推送接口杨汉汶2015-03-113.3新增批量订阅推送接口，删除3.2版本推送接口杨文胜2015-10-123.4新增订单分发接口，整理电子面单接口曹强2016-01-193.5重新调整在线下单接口曹强2016-03-013.6增加智选物流接口曹强2016-03-013.7分发及订阅接口更新任海洋2016-04-073.7.1推送接口更新任海洋2016-05-113.7.2电子面单新增通知快递员上门字段，推送接口新增货款状态推送詹益伟2016-07-014.0全新4.0接口，新增单号识别接口、智选物流接口、更新物流轨迹接口（订阅查询）詹益伟2016-9-264.0.1推送接口新增DataSign字段、订阅2.0新增仓库标识ID、智选物流接口新增字段胡蕾蕾2016-11-034.1新增在途监控（增值服务）曹强2016-12-134.1.1电子面单新增第三方订单号ThrOrderCode胡蕾蕾2017-1-104.2新增隐私快递胡蕾蕾2017-2-164.2.1新增代收货款业务胡蕾蕾2017-4-134.31、即时查询接口中轨迹状态新增0-无轨迹 2、普通回调接口中删除201状态3、修改智选物流接口文档4、电子面单接口添加特殊字符提示陈爱2017-4-254.41、 新增申请电子面单客户号接口2、 新增电子面单余额查询接口3、 新增电子面单单号回收接口4、 新增申请客户号信息推送接口陈爱2017-6-224.5新增短信接口李旭安2017-7-144.6电子面单接口新增支持邮政快递包裹吴明名词定义必须要求说明R必填（Required）。O可选（Optional）C报文中该参数在一定条件下可选（Conditional）1前言72概述82.1用户使用流程图82.2接口规范及说明92.2.1报文及报文编码92.2.2接入步骤102.2.3接口数据包结构112.2.4JSON 范例112.2.5流程示意图122.2.6网关地址122.3签名说明122.3.1关于签名122.3.2(C#)DataSign签名加密代码133下单153.1预约取件接口153.1.1功能说明153.1.2接口规则153.1.3系统级和应用级输入参数153.1.4返回结果参数183.1.5Json请求示例183.1.6Json请求返回示例193.2电子面单203.2.1功能说明203.2.2接口规则203.2.3系统级和应用级输入参数203.2.4返回结果参数243.3电子面单余量查询接口253.3.1功能说明253.3.2接口规则253.3.3系统级和应用级输入参数253.3.4返回结果参数263.3.5JSON请求示例263.3.6JSON返回示例263.4电子面单单号取消273.4.1功能说明273.4.2接口规则273.4.3系统级和应用级输入参数273.4.4返回结果参数283.4.5Json请求示例283.4.6Json请求返回示例283.5申请电子面单客户号283.5.1功能说明283.5.2接口规则293.5.3系统级和应用级输入参数293.5.4返回结果参数303.5.5Json请求示例303.5.6Json请求返回示例303.6申请客户号信息推送313.6.1功能说明313.6.2接口规则313.6.3系统级和应用级输入参数313.6.4返回结果参数313.6.5Json请求示例323.6.6Json请求返回示例323.7增值服务列表323.8安全号码接口333.8.1功能说明333.8.2接口规则333.8.3系统级和应用级输入参数333.8.4返回结果参数353.8.5JSON请求示例353.8.6JSON请求返回示例364轨迹查询374.1物流轨迹（即时查询）374.1.1功能说明374.1.2接口规则374.1.3系统级和应用级输入参数374.1.4返回结果参数374.1.5JSON请求示例384.1.6JSON返回示例384.2物流轨迹（订阅查询）404.2.1功能说明404.2.2接口规则404.2.3系统级和应用级输入参数404.2.4返回结果参数434.2.5JSON请求示例434.2.6JSON返回示例445异步推送（回调）接口455.1功能说明455.2接口规则455.3系统级和应用级输入参数455.3.1订阅查询结果（RequestType：101）465.3.2订阅查询（增值版）结果（RequestType：102）475.3.3货款状态（RequestType：107）485.4返回结果参数495.5JSON请求示例495.6JSON返回示例536智能服务536.1智选物流536.1.1.功能说明536.1.2.接口规则536.1.3.应用级输入参数546.1.4.返回结果参数566.1.5.JSON请求示例576.1.6.JSON返回示例596.2运费模板导入接口616.2.1.功能说明616.2.2.接口规则616.2.3.系统级输入参数616.2.4.应用级输入参数626.2.5.返回结果参数636.2.6.JSON请求示例636.2.7.JSON返回示例646.3单号识别656.3.1.功能说明656.3.2.接口规则656.3.3.系统级和应用级输入参数656.3.4.返回结果参数667在途监控（增值版）667.1物流轨迹（即时查询增值版）667.1.1功能说明667.1.2接口规则667.1.3系统级和应用级输入参数677.1.4返回结果参数677.1.5JSON请求示例687.1.6JSON返回示例687.2物流轨迹（订阅查询增值版）707.2.1功能说明707.2.2接口规则717.2.3系统级和应用级输入参数717.2.4返回结果参数747.2.5JSON请求示例747.2.6JSON返回示例758短信758.1短信发送758.1.1功能说明758.1.2接口规则758.1.3返回结果参数768.1.4JSON请求示例768.1.5JSON返回示例778.2短信模板778.2.1功能说明778.2.2接口规则778.2.3系统级和应用级输入参数778.2.4返回结果参数788.2.5JSON请求示例788.2.6JSON返回示例798.3短信黑名单798.3.1功能说明798.3.2接口规则798.3.3系统级和应用级输入参数798.3.4返回结果参数808.3.5JSON请求示例808.3.6JSON返回示例819附录819.1快递公司编码819.2常见问题解答Q&A819.3电子面单模板规格819.4返回编码列表8310技术支持831 前言快递鸟API旨在为电商、电商平台、物流工具、仓储系统等等系统提供专业、稳定、优质的物流服务，为不同的用户量身定做了专业的API接口服务，供不同的用户各取所需。本文档就各个API接口进行详细的说明，方便快递鸟的用户快速对接，方便快捷使用快递鸟服务。2 概述2.1 用户使用流程图快递鸟API全流程服务（电商）流程图基于电商现有的服务流程，快递鸟为电商、电商平台、ERP系统、仓储系统等系统在用户下单、选择物流、下单、打单、轨迹跟踪等关键节点，均提供了专业、高效的API接口，方便各个平台实现一次接入，便可使用国内外主流物理公司的服务。快递鸟API全流程服务（工具）流程图对于物流工具，基于用户的操作习惯，只需要输入单号，快递鸟即可完成后续的物流公司识别、查询轨迹等工作，为工具类用户提供一站式的服务。2.2 接口规范及说明2.2.1 报文及报文编码 Json格式。 编码格式：UTF-8 交互协议上统一用UTF-8，避免传递中文数据出现乱码。2.2.2 接入步骤 注册成为快递鸟用户(注：注册成功后进行实名认证，申请开通接口，后续会再对用户的注册信息进行审批)。注册成功后，登录用户管理后台就可以查看到用户所属唯一的商户ID和API key。按照快递鸟官网提示进行注册申请，注册成功后登录用户管理后台，您将得到由快递鸟提供的一组商户ID和API Key。商户ID是调用接口服务的身份证明，不可更改、不可转用，API Key是应用访问API的签名附加密钥，必须妥善保存。两者关系类似于登录帐号和密码，两者都会在签名和业务参数中使用。注册成功登录用户管理后台可以查看商户ID和API Key，需实名认证后才能申请开通接口。(1) 开发服务开发自身业务的服务，服务需遵循接口的定义规则。(2) 查看接口调用的DEMO快递鸟物流技术接口提供调用快递鸟物流接口的DEMO(.Net版本，Java版本，PHP版本)，包括网上在线订单下单、物流轨迹查询等物流行业标准化的下单操作流程与数据查询格式。提交接入处理的相关代码如有不明白的地方可与快递鸟物流技术接口人协作开发。DEMO下载地址： (如链接无法打开，请打开浏览器，在浏览器中输入)2.2.3 接口数据包结构图例 - 数据包结构 (系统级数据)2.2.4 JSON 范例 string userID = "1109259" string keyValue = "56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17"/加密私钥，由发货通提供 string url = "http:/api.kdniao.cc/Ebusiness/EbusinessOrderHandle.aspx" /请求地址 string DataType = "2" 2-json string charset="UTF-8"/字符编码采用UTF-8string jsonStr= ""OrderCode":"","ShipperCode":"SF","LogisticCode":"118461988807"" / JSON字符串string datasign = HttpUtility.UrlEncode(base64( MD5(jsonStr+keyValue, "UTF-8"),"UTF-8"),Encoding.UTF8);/把(jsonStr+AppKey)进行MD5加密，然后Base64编码，最后 进行URL(utf-8)编码string PostStr = "RequestType=1002&EBusinessID= userID &RequestData=jsonStr &DataSign= datasign&DataType=DataType" /请求报文参数string post = this.DoPost(url, PostStr);/ 通讯协议使用Http协议Post请求方式2.2.5 流程示意图2.2.6 网关地址测试接口：http:/testapi.kdniao.cc:8081/Ebusiness/EbusinessOrderHandle.aspx测试电商ID=1237100，AppKey=518a73d8-1f7f-441a-b644-33e77b49d846正式接口：http:/api.kdniao.cc/Ebusiness/EbusinessOrderHandle.aspx2.3 签名说明2.3.1 关于签名快递鸟和第三方电子商务公司系统进行对接，有一定的安全机制。采用IP认证加签名的方式对接，具体方案如下：(1) 防止数据被篡改在POST请求中会传递5个必须（R）参数RequestData=数据内容(URL编码:UTF-8)EBusinessID=电商IDRequestType=请求指令类型DataSign= 数据内容签名：把（请求内容（未编码）+ApiKey）进行MD5加密，然后Base64编码，最后进行URL（utf-8）编码DataType=返回数据类型(2-json)注：DataSign生成后，对方接收到数据后，以同样的算法进行签名，生成摘要，对比两者的摘要是否相同，如果不同，说明传递过程中发生数据篡改，对接过程中如有不明白之处可双方技术协作进行(2) 调用接口的身份认证注册成为快递鸟用户后，会生成对应的电商ID和AppKey，电商ID相当于用户名，AppKey相当于密码。注：请勿遗漏或传递可能递增大快递鸟接口调用维护举例说明：(a) 假设RequestData (JSON)内容为： “OrderCode”:”,“ShipperCode”:”SF”,”LogisticCode”:" 118954907573"经过URL(UTF-8)编码的内容为%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27SF%27%2c%27LogisticCode%27%3a%27118954907573%27%7d， EBusinessID为1109259，AppKey为56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17(b) 那么DataSign签名的内容为'OrderCode':'','ShipperCode':'SF','LogisticCode':'118954907573'56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17，经过md5和base64后的内容就为OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=，在经过URL(UTF-8)编码的内容为OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE%3d最终要发送的数据为RequestType=1002&EBusinessID=1109259&RequestData =%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27SF%27%2c%27LogisticCode%27%3a%27118954907573%27%7d &DataSign =OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE%3d& DataType=2(c) 接收方收到数据后，获得EBusinessID 和RequestData和DataSign等这几个数据。(d) 接收方对EBusinessID 得到AppKey，RequestData+AppKey的数据进行md5和base64后的内容就为OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=(e) 接收方判断签名后的数据跟传递过来的DataSign是否一致，如果一致进行业务操作，如果不一致返回错误。2.3.2 (C#)DataSign签名加密代码/<summary>/电商Sign签名/</summary>/<param name="content">内容</param>/<param name="keyValue">Appkey</param>/<param name="charset">URL编码 </param>/<returns>DataSign签名</returns>Public String Encrypt (String content, String keyValue, String charset)if (keyValue != null)return base64(MD5(content + keyValue, charset), charset);return base64(MD5(content, charset), charset);/<summary>/ 字符串MD5加密/</summary>/<param name="Text">要加密的字符串</param>/<returns>密文</returns>Private string MD5(string Text, string charset)byte buffer = System.Text.Encoding.GetEncoding(charset).GetBytes(Text);try System.Security.Cryptography.MD5CryptoServiceProvider check; check = new System.Security.Cryptography.MD5CryptoServiceProvider();byte somme = check.ComputeHash(buffer);string ret = ""foreach (byte a in somme) if (a < 16) ret += "0" + a.ToString("X");else ret += a.ToString("X"); return ret.ToLower();catch throw; Private static string base64(String str, String charset)returnConvert.ToBase64String(System.Text.Encoding.GetEncoding(charset).GetBytes(str);3 下单3.1 预约取件接口3.1.1 功能说明 预约取件接口是快递鸟提供给独立电商、仓储管理系统、物流供应链等物流系统平台使用的下单接口，为客户解决在线发货需求，客户通过网络选择快递公司发送请求通知贵公司有快递要发货，贵公司把数据通过此接口转发到快递鸟，由快递鸟为您提供通知快递员上门取件的服务。3.1.2 接口规则 (1)、订单编号(OrderCode)不可重复提交，重复提交系统会返回具体错误代码。 (2)、目前预约取件接口支持了：德邦、EMS、天地华宇、百世快递、京东、龙邦快递、顺丰快递、中通速递、韵达快递、圆通速递、宅急送，后续更多的快递公司正在对接中。 (3)、接口只支持Json格式参数，接口指令1001。只支持POST请求方式，utf-8编码。 (4)、支持增值服务，保价、代收货款、货款直退、货款垫付等。(5)、测试地址：http:/testapi.kdniao.cc:8081/api/oorderservice/ 正式地址：http:/api.kdniao.cc/api/oorderservice3.1.3 系统级和应用级输入参数系统级输入参数应用级输入参数类型是否必须描述RequestData（必填参数，请求内容，JSON格式,须和DataType一致）WarehouseIDStringO仓库标识(备用字段)WarehouseAddressStringO仓库地址(备用字段)CallBackStringO商户标识(备用字段)MemberIDStringO会员标识(备用字段)ShipperCodeStringR快递公司编码LogisticCodeStringO快递单号OrderCodeStringR订单编号MonthCodeStringC月结编码PayTypeIntR邮费支付方式:1-现付，2-到付，3-月结，4-第三方支付ExpTypeIntR快递类型：1-标准快件CostDoubleO寄件费（运费）OtherCostDoubleO其他费用ReceiverCompanyStringO收件人公司NameStringR收件人TelStringR电话与手机，必填一个MobileStringPostCodeStringO收件人邮编ProvinceNameStringR收件省（如广东省，不要缺少“省”）CityNameStringR收件市（如深圳市，不要缺少“市”）ExpAreaNameStringO收件区（如福田区，不要缺少“区”或“县”）AddressStringR收件人详细地址SenderCompanyStringO发件人公司NameStringR发件人TelStringR电话与手机，必填一个MobileStringPostCodeStringO发件人邮编ProvinceNameStringO发件省（如广东省，不要缺少“省”）CityNameStringR发件市（如深圳市，不要缺少“市”）ExpAreaNameStringO发件区（如福田区，不要缺少“区”或“县”）AddressStringR发件详细地址StartDateStringO上门取货时间段:"yyyy-MM-dd HH:mm:ss"格式化，本文中所有时间格式相同EndDateStringOWeightDoubleO物品总重量kgQuantityIntO件数/包裹数VolumeDoubleO物品总体积m3RemarkStringO备注AddServiceNameString0增值服务名称ValueString0增值服务值CustomerIDString0客户标识(选填)CommodityGoodsNameStringR商品名称GoodsCodeStringO商品编码GoodsquantityIntO件数GoodsPriceDoubleO商品价格GoodsWeightDoubleO商品重量kgGoodsDescStringO商品描述GoodsVolDoubleO商品体积m3EBusinessIDStringR电商IDRequestTypeStringR请求指令类型：1001DataSignStringR数据内容签名DataTypeStringR请求、返回数据类型：2-json；3.1.4 返回结果参数参数名称类型必须要求说明EBusinessIDStringR电商用户IDOrderOrderCodeStringR订单编号ShipperCodeStringR快递公司编码LogisticCodeStringO快递单号SuccessBoolR成功与否ResultCodeStringR结果编号ReasonStringO失败原因UniquerRequestNumberStringR唯一标识3.1.5 Json请求示例 "OrderCode": "012657018199", "ShipperCode": "SF", "PayType": 1, "MonthCode": "7553045845", "ExpType": 1, "Cost": 1.0, "OtherCost": 1.0, "Sender": "Company": "LV", "Name": "Taylor", "Mobile": "15018442396", "ProvinceName": "上海", "CityName": "上海", "ExpAreaName": "青浦区", "Address": "明珠路" , "Receiver": "Company": "GCCUI", "Name": "Yann", "Mobile": "15018442396", "ProvinceName": "北京", "CityName": "北京", "ExpAreaName": "朝阳区", "Address": "三里屯街道" , "Commodity": "GoodsName": "鞋子", "Goodsquantity": 1, "GoodsWeight": 1.0 , "AddService": "Name": "COD", "Value": "1020" , "Weight": 1.0, "Quantity": 1, "Volume": 0.0, "Remark": "小心轻放"3.1.6 Json请求返回示例 "EBusinessID": "1237100", "Success": true, "Order": "OrderCode": "012657018199", " ShipperCode ": " SF ", " LogisticCode ": "" , "ResultCode": "100", "Reason": ""3.2 电子面单3.2.1 功能说明电子面单接口是快递鸟提供给独立电商、仓储管理系统、物流供应链等物流系统平台使用的下单接口，满足客户在线发货需求并提供打印面单的服务，客户通过网络选择物流公司发送请求通知贵公司有快递要发货，贵公司把数据通过此接口转发到快递鸟，由快递鸟为您通知对应的快递公司快递员上门取件。电子面单成功下单后，快递鸟系统内将自动订阅，一旦轨迹发生变化时，快递鸟将调用客户方推送接收接口。同时若客户使用代收货款服务，快递鸟会将代收货款的货款状态独立推送给用户。3.2.2 接口规则(1)、只支持Json格式。接口指令1007。(2)、订单编号(OrderCode)不可重复提交，重复提交系统会返回具体错误代码。(3)、目前接口支持了：顺丰（SF）、EMS（EMS）、宅急送（ZJS）、圆通（YTO）、百世快递（HTKY）、中通（ZTO）、韵达（YD）、申通（STO）、德邦（DBL）、优速（UC）、京东（JD）、信丰（XFEX）、全峰（QFKD）、跨越速运（KYSY）、安能小包（ANE）、快捷快递（FAST）、国通（GTO）、天天快递（HHTT）、邮政快递包裹（YZPY），后续更多的快递公司正在对接中。散户模式（无需电子面单客户号）支持快递公司：顺丰（SF）、EMS（EMS）（仅支持广东省内发货）、快捷快递（FAST）、宅急送（ZJS）、邮政快递包裹（YZPY），后续更多的快递公司正在对接中。(4)、测试地址：http:/testapi.kdniao.cc:8081/api/eorderservice/(5)、正式地址：http:/api.kdniao.cc/api/EOrderService (6)、请求报文中不允许出现以下特殊字符： ' " # & + < >3.2.3 系统级和应用级输入参数系统级输入参数应用级输入参数类型是否必须描述RequestData（必填参数，请求内容，JSON格式,须和DataType一致）CallBackStringO用户自定义回调信息MemberIDStringO会员标识平台方与快递鸟统一用户标识的商家IDCustomerNameStringO电子面单客户账号（与快递网点申请或通过快递鸟官网申请或通过申请电子面单客户号申请）CustomerPwdStringO电子面单密码SendSiteStringO收件网点标识ShipperCodeStringR快递公司编码LogisticCodeStringO快递单号ThrOrderCodeStringO第三方订单号OrderCodeStringR订单编号MonthCodeStringC月结编码PayTypeIntR邮费支付方式:1-现付，2-到付，3-月结，4-第三方支付ExpTypeStringR快递类型：1-标准快件IsNoticeIntO是否通知快递员上门揽件：0-通知；1-不通知；不填则默认为1CostDoubleO寄件费（运费）OtherCostDoubleO其他费用ReceiverCompanyStringO收件人公司NameStringR收件人TelStringR电话与手机，必填一个MobileStringPostCodeStringO收件人邮编ProvinceNameStringR收件省（如广东省，不要缺少“省”）CityNameStringR收件市（如深圳市，不要缺少“市”）ExpAreaNameStringO收件区（如福田区，不要缺少“区”或“县”）AddressStringR收件人详细地址SenderCompanyStringO发件人公司NameStringR发件人TelStringR电话与手机，必填一个MobileStringPostCodeStringO发件人邮编ProvinceNameStringR发件省（如广东省，不要缺少“省”）CityNameStringR发件市（如深圳市，不要缺少“市”）ExpAreaNameStringO发件区（如福田区，不要缺少“区”或“县”）AddressStringR发件详细地址StartDateStringO上门取货时间段:"yyyy-MM-dd HH:mm:ss"格式化，本文中所有时间格式相同EndDateStringOWeightDoubleO物品总重量kgQuantityIntO件数/包裹数VolumeDoubleO物品总体积m3RemarkStringO备注AddServiceNameString0增值服务名称ValueString0增值服务值CustomerIDString0客户标识(选填)CommodityGoodsNameStringR商品名称GoodsCodeStringO商品编码GoodsquantityIntO件数GoodsPriceDoubleO商品价格GoodsWeightDoubleO商品重量kgGoodsDescStringO商品描述GoodsVolDoubleO商品体积m3IsReturnPrintTemplateStringO返回电子面单模板：0-不需要；1-需要IsSendMessageIntO是否订阅短信0-不需要；1-需要TemplateSizeStringO模板尺寸EBusinessIDStringR商户IDRequestTypeStringR请求指令类型：1007DataSignStringR数据内容签名DataTypeStringR请求、返回数据类型： 2-json3.2.4 返回结果参数l 同步返回参数名称类型必须要求说明EBusinessIDStringR电商用户IDOrderOrderCodeStringR订单编号ShipperCodeStringR快递公司编码LogisticCodeSt