快递鸟物流接口技术文档.docx
《快递鸟物流接口技术文档.docx》由会员分享，可在线阅读，更多相关《快递鸟物流接口技术文档.docx（118页珍藏版）》请在冰点文库上搜索。
快递鸟物流接口技术文档
快递鸟接口（API）技术文档
版本
日期
版本
说明
作者
2014-12-01
3.0
重新整理，根据功能分类，部分有调整
杨文胜
2014-01-11
3.1
对接口的说明进行了注释，提高可读性
杨汉汶
2014-01-13
3.2
新增推送接口
杨汉汶
2015-03-11
3.3
新增批量订阅推送接口，删除3.2版本推送接口
杨文胜
2015-10-12
3.4
新增订单分发接口，整理电子面单接口
曹强
2016-01-19
3.5
重新调整在线下单接口
曹强
2016-03-01
3.6
增加智选物流接口
曹强
2016-03-01
3.7
分发及订阅接口更新
任海洋
2016-04-07
3.7.1
推送接口更新
任海洋
2016-05-11
3.7.2
电子面单新增通知快递员上门字段，推送接口新增货款状态推送
詹益伟
2016-07-01
4.0
全新4.0接口，新增单号识别接口、智选物流接口、更新物流轨迹接口（订阅查询）
詹益伟
2016-9-26
4.0.1
推送接口新增DataSign字段、订阅2.0新增仓库标识ID、智选物流接口新增字段
胡蕾蕾
2016-11-03
4.1
新增在途监控（增值服务）
曹强
2016-12-13
4.1.1
电子面单新增第三方订单号ThrOrderCode
胡蕾蕾
2017-1-10
4.2
新增隐私快递
胡蕾蕾
2017-2-16
4.2.1
新增代收货款业务
胡蕾蕾
2017-4-13
4.3
1、即时查询接口中轨迹状态新增0-无轨迹
2、普通回调接口中删除201状态
3、修改智选物流接口文档
4、电子面单接口添加特殊字符提示
陈爱
2017-4-25
4.4
1、新增申请电子面单客户号接口
2、新增电子面单余额查询接口
3、新增电子面单单号回收接口
4、新增申请客户号信息推送接口
陈爱
2017-6-22
4.5
新增短信接口
李旭安
2017-7-14
4.6
电子面单接口新增支持邮政快递包裹
吴明
名词定义
必须要求
说明
R
必填（Required）。
O
可选（Optional）
C
报文中该参数在一定条件下可选（Conditional）
1
前言
快递鸟API旨在为电商、电商平台、物流工具、仓储系统等等系统提供专业、稳定、优质的物流服务，为不同的用户量身定做了专业的API接口服务，供不同的用户各取所需。
本文档就各个API接口进行详细的说明，方便快递鸟的用户快速对接，方便快捷使用快递鸟服务。
2概述
2.1用户使用流程图
快递鸟API全流程服务（电商）流程图
基于电商现有的服务流程，快递鸟为电商、电商平台、ERP系统、仓储系统等系统在用户下单、选择物流、下单、打单、轨迹跟踪等关键节点，均提供了专业、高效的API接口，方便各个平台实现一次接入，便可使用国内外主流物理公司的服务。
快递鸟API全流程服务（工具）流程图
对于物流工具，基于用户的操作习惯，只需要输入单号，快递鸟即可完成后续的物流公司识别、查询轨迹等工作，为工具类用户提供一站式的服务。
2.2接口规X及说明
2.2.1报文及报文编码
Json格式。
编码格式：
UTF-8
交互协议上统一用UTF-8，避免传递中文数据出现乱码。
2.2.2接入步骤
注册成为快递鸟用户（注：
注册成功后进行实名认证，申请开通接口，后续会再对用户的注册信息进行审批）。
注册成功后，登录用户管理后台就可以查看到用户所属唯一的商户ID和APIkey。
按照快递鸟官网提示进行注册申请，注册成功后登录用户管理后台，您将得到由快递鸟提供的一组商户ID和APIKey。
商户ID是调用接口服务的##明，不可更改、不可转用，APIKey是应用访问API的签名附加密钥，必须妥善保存。
两者关系类似于登录##和密码，两者都会在签名和业务参数中使用。
注册成功登录用户管理后台可以查看商户ID和APIKey，需实名认证后才能申请开通接口。
（1）开发服务
开发自身业务的服务，服务需遵循接口的定义规则。
（2）查看接口调用的DEMO
快递鸟物流技术接口提供调用快递鸟物流接口的DEMO（.Net版本，Java版本，PHP版本），包括网上在线订单下单、物流轨迹查询等物流行业标准化的下单操作流程与数据查询格式。
提交接入处理的相关代码如有不明白的地方可与快递鸟物流技术接口人协作开发。
DEMO下载地址：
.kdniao./download（如无法打开，请打开浏览器，在浏览器中输入）
2.2.3接口数据包结构
图例-数据包结构（系统级{数据}）
2.2.4JSONX例
stringuserID="1109259";
stringkeyValue="56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17";//加密私钥，由发货通提供
stringurl="api.kdniao.cc/Ebusiness/EbusinessOrderHandle.aspx";//请求地址
stringDataType="2";2-json
stringcharset="UTF-8";//字符编码采用UTF-8
stringjsonStr="{\"OrderCode\":
\"\",\"ShipperCode\":
\"SF\",\"LogisticCode\":
\"7\"}";//JSON字符串string
datasign=HttpUtility.UrlEncode（base64（MD5（jsonStr+keyValue,"UTF-8"）,"UTF-8"）,Encoding.UTF8）;//把（jsonStr+AppKey）进行MD5加密，然后Base64编码，最后进行URL（utf-8）编码
stringPostStr="RequestType=1002&EBusinessID=userID&RequestData=jsonStr&DataSign=datasign&DataType=DataType";//请求报文参数
stringpost=this.DoPost（url,PostStr）;//通讯协议使用Http协议Post请求方式
2.2.5流程示意图
2.2.6网关地址
测试接口：
testapi.kdniao.cc:
8081/Ebusiness/EbusinessOrderHandle.aspx
测试电商ID==1237100，AppKey==518a73d8-1f7f-441a-b644-33e77b49d846
正式接口：
api.kdniao.cc/Ebusiness/EbusinessOrderHandle.aspx
2.3签名说明
2.3.1关于签名
快递鸟和第三方电子商务公司系统进行对接，有一定的安全机制。
采用IP认证加签名的方式对接，具体方案如下：
（1）防止数据被篡改
在POST请求中会传递5个必须（R）参数
RequestData==数据内容（URL编码:
UTF-8）
EBusinessID==电商ID
RequestType=请求指令类型
DataSign==数据内容签名：
把（请求内容（未编码）+ApiKey）进行MD5加密，然后Base64编码，最后进行URL（utf-8）编码
DataType==返回数据类型（2-json）
注：
DataSign生成后，对方接收到数据后，以同样的算法进行签名，生成摘要，对比两者的摘要是否相同，如果不同，说明传递过程中发生数据篡改，对接过程中如有不明白之处可双方技术协作进行
（2）调用接口的身份认证
注册成为快递鸟用户后，会生成对应的电商ID和AppKey，电商ID相当于用户名，AppKey相当于密码。
注：
请勿遗漏或传递可能递增大快递鸟接口调用维护
举例说明：
（a）假设RequestData（JSON）内容为：
{“OrderCode”:
””,“ShipperCode”:
”SF”,”LogisticCode”:
"3"}经过URL（UTF-8）编码的内容为%7b%27OrderCode%27%3a%27%27%2c%27ShipperCode%27%3a%27SF%27%2c%27LogisticCode%27%3a%573%27%7d，EBusinessID为1109259，AppKey为56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17
（b）那么DataSign签名的内容为
{'OrderCode':
'','ShipperCode':
'SF','LogisticCode':
'3'}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%573%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签名加密代码
///
///电商Sign签名
///
///内容
///Appkey
///URL编码
///DataSign签名
PublicStringEncrypt（Stringcontent,StringkeyValue,Stringcharset）
{
if（keyValue!
=null）
{
returnbase64（MD5（content+keyValue,charset）,charset）;
}
returnbase64（MD5（content,charset）,charset）;
}
///
///字符串MD5加密
///
///要加密的字符串
///密文
PrivatestringMD5（stringText,stringcharset）
{
byte[]buffer=System.Text.Encoding.GetEncoding（charset）.GetBytes（Text）;
try
{
System.Security.Cryptography.MD5CryptoServiceProvidercheck;
check=newSystem.Security.Cryptography.MD5CryptoServiceProvider（）;
byte[]somme=check.puteHash（buffer）;
stringret="";
foreach（byteainsomme）
{
if（a<16）
ret+="0"+a.ToString（"X"）;
else
ret+=a.ToString（"X"）;
}
returnret.ToLower（）;
}
catch
{
throw;
}
}
Privatestaticstringbase64（Stringstr,Stringcharset）
{
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）、测试地址：
testapi.kdniao.cc:
8081/api/oorderservice/
正式地址：
api.kdniao.cc/api/oorderservice
3.1.3系统级和应用级输入参数
系统级输入参数
应用级输入参数
类型
是否必须
描述
RequestData（必填参数，请求内容，JSON格式,须和DataType一致）
WarehouseID
String
O
仓库标识（备用字段）
WarehouseAddress
String
O
仓库地址（备用字段）
CallBack
String
O
商户标识（备用字段）
MemberID
String
O
会员标识（备用字段）
ShipperCode
String
R
快递公司编码
LogisticCode
String
O
快递单号
OrderCode
String
R
订单编号
MonthCode
String
C
月结编码
PayType
Int
R
邮费支付方式:
1-现付，2-到付，3-月结，4-第三方支付
ExpType
Int
R
快递类型：
1-标准快件
Cost
Double
O
寄件费（运费）
OtherCost
Double
O
其他费用
Receiver
pany
String
O
收件人公司
Name
String
R
收件人
Tel
String
R
与手机，必填一个
Mobile
String
PostCode
String
O
收件人邮编
ProvinceName
String
R
收件省（如##省，不要缺少“省”）
CityName
String
R
收件市（如##市，不要缺少“市”）
ExpAreaName
String
O
收件区（如福田区，不要缺少“区”或“县”）
Address
String
R
收件人详细地址
Sender
pany
String
O
发件人公司
Name
String
R
发件人
Tel
String
R
与手机，必填一个
Mobile
String
PostCode
String
O
发件人邮编
ProvinceName
String
O
发件省（如##省，不要缺少“省”）
CityName
String
R
发件市（如##市，不要缺少“市”）
ExpAreaName
String
O
发件区（如福田区，不要缺少“区”或“县”）
Address
String
R
发件详细地址
StartDate
String
O
上门取货时间段:
"yyyy-MM-ddHH:
mm:
ss"格式化，本文中所有时间格式相同
EndDate
String
O
Weight
Double
O
物品总重量kg
Quantity
Int
O
件数/包裹数
Volume
Double
O
物品总体积m3
Remark
String
O
备注
AddService
Name
String
0
增值服务名称
Value
String
0
增值服务值
CustomerID
String
0
客户标识（选填）
modity
GoodsName
String
R
商品名称
GoodsCode
String
O
商品编码
Goodsquantity
Int
O
件数
GoodsPrice
Double
O
商品价格
GoodsWeight
Double
O
商品重量kg
GoodsDesc
String
O
商品描述
GoodsVol
Double
O
商品体积m3
EBusinessID
String
R
电商ID
RequestType
String
R
请求指令类型：
1001
DataSign
String
R
数据内容签名
DataType
String
R
请求、返回数据类型：
2-json；
3.1.4返回结果参数
参数名称
类型
必须要求
说明
EBusinessID
String
R
电商用户ID
Order
OrderCode
String
R
订单编号
ShipperCode
String
R
快递公司编码
LogisticCode
String
O
快递单号
Success
Bool
R
成功与否
ResultCode
String
R
结果编号
Reason
String
O
失败原因
UniquerRequestNumber
String
R
唯一标识
3.1.5Json请求示例
{
"OrderCode":
"9",
"ShipperCode":
"SF",
"PayType":
1,
"MonthCode":
"7553045845",
"ExpType":
1,
"Cost":
1.0,
"OtherCost":
1.0,
"Sender":
{
"pany":
"LV",
"Name":
"Taylor",
"Mobile":
"",
"ProvinceName":
"##",
"CityName":
"##",
"ExpAreaName":
"青浦区",
"Address":
"明珠路"
},
"Receiver":
{
"pany":
"GCCUI",
"Name":
"Yann",
"Mobile":
"",
"ProvinceName":
"",
"CityName":
"",
"ExpAreaName":
"##区",
"Address":
"三里屯街道"
},
"modity":
[
{
"GoodsName":
"鞋子",
"Goodsquantity":
1,
"GoodsWeight":
1.0
}
],
"AddService":
[
{
"Name":
"COD",
"Value":
"1020"
}
],
"Weight":
1.0,
"Quantity":
1,
"Volume":
0.0,
"Remark":
"小心轻放"
}
3.1.6Json请求返回示例
{
"EBusinessID":
"1237100",
"Success":
true,
"Order":
{
"OrderCode":
"9",
"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）、测试地址：
testapi.kdniao.cc:
8081/api/eorderservice/
（5）、正式地址：
api.kdniao.cc/api/EOrderService
（6）、请求报文中不允许出现以下特殊字符：
'"#&+<>
3.2.3系统级和应用级输入参数
系统级输入参数
应用级输入参数
类型
是否必须
描述
RequestData（必填参数，请求内容，JSON格式,须和DataType一致）
CallBack
String
O
用户自定义回调信息
MemberID
String
O
会员标识
平台方与快递鸟统一用户标识的商家ID
CustomerName
String
O
电子面单客户账号
（与快递网点申请或通过快递鸟官网申请或通过申请电子面单客户号
升级会员 