常用电子面单接口对接技术文档

Posted 2020-08-11

 

一.电子面单接口类型及定义

1. 快递电子面单接口：快递公司自己开发的电子面单服务， 商家使用必须快递公司上门做系统对接，使用一家快递则需要对接一次。

2.菜鸟电子面单接口：可一次对接15家快递公司， 无需和每一家快递公司做对接。支持快递有四通一达、EMS、宅急送、德邦、优速、天天、快捷、全峰等15家常用快递公司，其中不包括顺丰。

3.快递鸟电子面单接口：可一次对接15家快递公司， 无需和每一家快递公司做对接。支持快递有四通一达、顺丰、EMS、宅急送、德邦、优速等15家快递公司，对顺丰有电子面单服务需求的可以选择顺丰自有的电子面单或者是快递鸟电子面单。

 

二.开通使用流程

1.快递电子面单

a. 和多家快递公司申请账号

b.分别进行接口对接

c.电子面单服务用户向快递网点申请开通及确认合作细节

 

2.菜鸟电子面单

a.向菜鸟提交对接申请

b.和菜鸟进行接口对接

c.电子面单服务用户向菜鸟申请账号

d.电子面单服务用户向快递网点申请开通及确认合作细节

 

3.快递鸟电子面单

a. 进入http://www.kdniao.com/reg申请账号，获取专属的ID和KEY

b.和快递鸟进行接口对接

c.电子面单服务用户向快递网点申请开通及确认合作细节

 

接口类型较多，以下先附上快递鸟电子面单接口调用方式，希望对大家有所帮助。后面将逐个对菜鸟电子面单、顺丰电子面单等接口调用方式做整理说明。

三.接口规则

(1)、只支持Json格式。接口指令1007。

(2)、接口平台：快递鸟

    (3)、测试地址：http://testapi.kdniao.cc:8081/api/eorderservice/

四.系统级输入参数

参数名称	类型	必须要求	说明
RequestData	String	R	请求内容，JSON或XML格式,须和DataType一致
EBusinessID	String	R	电商ID
RequestType	String	R	请求指令类型：1007
DataSign	String	R	数据内容签名
DataType	String	O	请求、返回数据类型：1-xml,2-json；默认为xml格式

五.应用级输入参数

参数名称			类型	是否必须	描述
CallBack			String	O	用户自定义回调信息
MemberID			String	O	会员标识 平台方与快递鸟统一用户标识的商家ID
CustomerName			String	O	电子面单客户账号 （与快递网点申请）
CustomerPwd			String	O	电子面单密码
SendSite			String	O	收件网点标识
ShipperCode			String	R	快递公司编码
LogisticCode			String	O	快递单号
OrderCode			String	R	订单编号
MonthCode			String	C	月结编码
PayType			Int	R	邮费支付方式: 1-现付，2-到付，3-月结，4-第三方支付
ExpType			String	R	快递类型：1-标准快件
IsNotice			Int	O	是否通知快递员上门揽件：0-不通知；1-通知；不填则默认为1
Cost			Double	O	寄件费（运费）
OtherCost			Double	O	其他费用
Receiver	Company		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	Company		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-dd HH: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	客户标识(选填)
Commodity		GoodsName	String	R	商品名称
		GoodsCode	String	O	商品编码
		Goodsquantity	Int	O	件数
		GoodsPrice	Double	O	商品价格
		GoodsWeight	Double	O	商品重量kg
		GoodsDesc	String	O	商品描述
		GoodsVol	Double	O	商品体积m3
IsReturnPrintTemplate			String	O	返回电子面单模板： 0-不需要；1-需要

六.返回结果参数

参数名称		类型	必须要求	说明
EBusinessID		String	R	电商用户ID
Order	OrderCode	String	R	订单编号
	ShipperCode	String	R	快递公司编码
	LogisticCode	String	R	快递单号
	MarkDestination	String	O	大头笔
	OriginCode	String	O	始发地区域编码
	OriginName	String	O	始发地/始发网点
	DestinatioCode	String	O	目的地区域编码
	DestinatioName	String	O	目的地/到达网点
	SortingCode	String	O	分拣编码
	PackageCode	String	O	集包编码
Success		Bool	R	成功与否
ResultCode		String	R	错误编码
Reason		String	O	失败原因
UniquerRequestNumber		String	R	唯一标识
PrintTemplate		String	O	面单打印模板
EstimatedDeliveryTime		String	O	订单预计到货时间yyyy-mm-dd
Callback		String	O	用户自定义回调信息

 

七.JSON请求示例

{   "OrderCode": "012657700387",   "ShipperCode": "HTKY",   "PayType": 1,   "ExpType": 1,   "Cost": 1.0,   "OtherCost": 1.0,   "Sender": {     "Company": "LV",     "Name": "Taylor",     "Mobile": "15018442396",     "ProvinceName": "上海",     "CityName": "上海",     "ExpAreaName": "青浦区",     "Address": "明珠路73号"   },   "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": "小心轻放",   "IsReturnPrintTemplate":1 }

八.JSON返回示例

{   "EBusinessID": "1237100",   "Order": {     "OrderCode": "012657700387",     "ShipperCode": "HTKY",     "LogisticCode": "50002498503427",     "MarkDestination": "京-朝阳(京-1)",     "OriginCode": "200000",     "OriginName": "上海分拨中心",     "PackageCode": "北京"   },   "PrintTemplate":"此处省略打印模板html内容",   "EstimatedDeliveryTime":"2016-03-06",   "Callback":"调用时传入的Callback",   "Success": true,   "ResultCode": "100",   "Reason": "成功" }

九.接口及签名说明

1）、支持http传输协议

2）、支持的数据传输格式

    Json/Xml(暂不支持<content/>这种形式)。

    编码格式：UTF-8

    交互协议上统一用UTF-8，避免传递中文数据出现乱码。

3）、接入步骤

按照快递鸟官网提示进行注册申请，注册成功并且登录，得到一组电商ID和AppKey。电商ID是调用接口服务的身份证明，不可更改、不可转用，AppKey是应用访问API的签名附加密钥，必须妥善保存。两者关系类似于登录帐号和密码，两者都会在签名和业务参数中使用。

注册成功登录之后：进入我的服务查看ID和AppKey

 

(1)      开发服务

开发自身业务的服务，服务需按照后面接口的定义规则。

(2)      查看接口调用的DEMO

快递鸟物流技术接口提供调用快递鸟物流接口的DEMO(.Net版本)，包括网上在线订单下单、物流轨迹查询等物流行业标准化的下单操作流程与数据查询格式。。

DEMO下载地址：http://www.kdniao.com/ResourceDownload.aspx (如链接无法打开，请打开浏览器，在浏览器中输入)

4）、接口数据包结构

图例 - 数据包结构 (系统级{数据})

 

5）、XML范例/JSON 范例

 string userID = "1109259";

 string keyValue = "56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17";//加密私钥，由发货通提供

 string url = "http://api.kdniao.cc:8081/Ebusiness/EbusinessOrderHandle.aspx";  //请求地址

 string DataType = "1"; //1-xml;2-json

 string charset="UTF-8";//字符编码采用UTF-8

 string xmlStr = "<Content><OrderCode></OrderCode><ShipperCode>SF</ShipperCode><LogisticCode>118650888088</LogisticCode></Content>";// XML字符串

 string xmlStr = "{\"OrderCode\":\"\",\"ShipperCode\":\"SF\",\"LogisticCode\":\"118461988807\"}"; // JSON字符串

string datasign = MD5(xmlStr+keyValue, "UTF-8");//生成加密签名加密通过对参数xmlStr+ keyValue得到加密后的字符串

string PostStr = "RequestType=1002&EBusinessID= userID &RequestData=xmlStr &DataSign= datasign&DataType=DataType"; //请求报文参数

string post = this.DoPost(url, PostStr);// 通讯协议使用Http协议Post请求方式

6）、流程示意图

 

7）、网关地址

测试接口：http://api.kdniao.cc:8081/Ebusiness/EbusinessOrderHandle.aspx

测试电商ID==1237100，AppKey==518a73d8-1f7f-441a-b644-33e77b49d846

正式接口：http://api.kdniao.cc/Ebusiness/EbusinessOrderHandle.aspx

注意：正式(自行注册)环境下使用时，需提供请求的IP给快递鸟登记

8）、关于签名

快递鸟和第三方电子商务公司系统进行对接，有一定的安全机制。采用IP认证加签名的方式对接，具体方案如下：

(1)      防止数据被篡改

在POST请求中会传递5个参数

4个必须参数：

RequestType=请求指令类型

EBusinessID==电商ID

RequestData==数据内容(URL编码:UTF-8)

DataSign== 签名摘要(URL编码:UTF-8(base64(MD5(数据内容 +AppKey))))

       1个可选参数：

              DataType==返回数据类型(1-xml,2-json；默认为2格式)

注：DataSign生成后，对方接收到数据后，以同样的算法进行签名，生成摘要，对比两者的摘要是否相同，如果不同，说明传递过程中发生数据篡改，对接过程中如有不明白之处可双方技术协作进行

(2)      调用接口的身份认证

注册成为快递鸟用户后，会生成对应的电商ID和AppKey，电商ID相当于用户名，AppKey相当于密码。注：请勿遗漏或传递可能递增大快递鸟接口调用维护

举例说明：

(a)      假设RequestData (XML)内容为： <Content><ShipperCode>SF</ShipperCode><LogisticCode>118954907573</LogisticCode></Content>，经过URL(UTF-8)编码的内容为%3cContent%3e%3cShipperCode%3eSF%3c%2fShipperCode%3e%3cLogisticCode%3e118954907573%3c%2fLogisticCode%3e%3c%2fContent%3e， EBusinessID为1109259，AppKey为56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17

(b)      那么DataSign签名的内容为<Content><ShipperCode>SF</ShipperCode><LogisticCode>118954907573</LogisticCode></Content>56da2cf8-c8a2-44b2-b6fa-476cd7d1ba17，经过md5和base64后的内容就为YzBjODA3MjA2NmViM2ZlZGMyNWNjMDA0NDRiMDdmOTE=，在经过URL(UTF-8)编码的内容为YzBjODA3MjA2NmViM2ZlZGMyNWNjMDA0NDRiMDdmOTE%3d

(c)      最终要发送的数据为RequestType=1002&EBusinessID=1109259&RequestData =%3cContent%3e%3cShipperCode%3eSF%3c%2fShipperCode%3e%3cLogisticCode%3e118954907573%3c%2fLogisticCode%3e%3c%2fContent%3e &DataSign = YzBjODA3MjA2NmViM2ZlZGMyNWNjMDA0NDRiMDdmOTE%3d& DataType=2

(d)      接收方收到数据后，获得EBusinessID 和RequestData和DataSign等这几个数据。

(e)      接收方对EBusinessID 得到AppKey，RequestData+AppKey的数据进行md5和base64后的内容就为YzBjODA3MjA2NmViM2ZlZGMyNWNjMDA0NDRiMDdmOTE=

(f)       接收方判断签名后的数据跟传递过来的DataSign是否一致，如果一致进行业务操作，如果不一直返回错误。

9）、(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)); }