上门取件API-下单接口
上一篇文章我们介绍了上门取件服务的重要性，这次我们来聊聊如何对接取件接口。
前期工作就不多说了，快递鸟官网注册，获取key,这些基础步骤以前有提到。
这次我们还是以C#为例来讲解接口。
首先是接口规范：
一、接口描述/说明
1. 上门取件下单接口
（1）此功能是为买家在退货时，提供的一种省心，便捷的物流服务，当买家购买的商品在申请换货或者发起维权投诉时需要退货，不需要自己邮寄商品，由物流公司安排快递员上门取件的一项服务。
（2）下单需指定相应的快递公司编码，格式不对或则编码错误都会返回失败的信息。
（3）接口支持的消息接收方式为HTTP POST，请求方法的编码格式(utf-8)："application/x-www-form-urlencoded;charset=utf-8"。避免传递中文数据是出现乱码
（4）接口地址：
沙箱地址：http://sandboxapi.kdniao.com:8080/kdniaosandbox/gateway/exterfaceInvoke.json
正式地址(不加密)：
http://api.kdniao.com/api/OOrderService
正式地址(加密)：
https://api.kdniao.com/api/OOrderService
接口规则
- 请求报文中不允许出现以下特殊字符： ' " # & + < > % \
- 预约时提供的收寄方信息必须真实准确。
- 用户提供的寄件地址若超出快递公司服务范围，则无快递员上门揽件。
- 预约成功后，仅顺丰会返回快递单号；其他快递公司不会返回快递单号，快递员上门取件时通过其他方式或者手写快递单收件。
- 因用户原因(如：恶意下单、批量下单长时间不发货等)导致快递公司投诉超过3次，快递鸟将停用此用户接口权限。
- 通过快递柜预约成功的用户，凭寄件码在3天内(期间会为您保留快递柜空位，快递员不会上门取件)将货物存至快递柜内，存件成功后快递员会取件发货。
目前快递鸟接口支持预约取件的快递公司：顺丰速运、百世快递、中通快递、圆通速递、韵达速递、优速快递、德邦快递、邮政国内标快、EMS、天天快递、邮政快递包裹、宅急送、远成快运(YCWL)、安能快递、天地华宇、增益快递、运东西网、品骏快递、通用物流、壹米滴答、承诺达、安迅物流、快8速运、申通快递、顺心捷达、一智通。
支持预约取件的快递柜：丰巢快递柜(ShipperCode为FCBOX)。
支持预约取件的同城配：闪送、大马鹿。
图例 - 数据包结构 (系统级参数{应用级参数})
系统级参数
|
参数名称 |
类型 |
说明 |
必须要求 |
|
RequestData |
String |
请求内容需进行URL(utf-8)编码。请求内容JSON格式，须和DataType一致。 |
R |
|
EBusinessID |
String |
商户ID，请在我的服务页面查看。 |
R |
|
RequestType |
String |
请求指令类型：1801 |
R |
|
DataSign |
String |
数据内容签名：把(请求内容(未编码)+AppKey)进行MD5加密，然后Base64编码，最后 进行URL(utf-8)编码。详细过程请查看Demo。 |
R |
|
DataType |
String |
请求、返回数据类型：2-json； |
R |
备注：R-必填（Required），O-可选（Optional），C-报文中该参数在一定条件下可选（Conditional）
前面介绍过快递即时查询接口，订阅推送接口，我们发现快递鸟提供的所有接口统一使用同一结构，系统级参数都一样，根据不同的请求接口指令接入不同的接口
应用级参数
|
名称 |
类型(字符长度) |
是否必须 |
描述 |
||
|
WarehouseID |
String(50) |
O |
仓库标识(备用字段) |
||
|
WarehouseAddress |
String(50) |
O |
仓库地址(备用字段) |
||
|
Callback |
String(50) |
O |
用户自定义回传字段 |
||
|
MemberID |
String(50) |
O |
ERP系统、电商平台等系统或平台类型用户的会员ID或店铺账号等唯一性标识，用于区分其用户 |
||
|
OrderCode |
String(30) |
R |
订单编号(自定义，不可重复) |
||
|
PayType |
Int(1) |
R |
运费支付方式： 1-现付，2-到付，3-月结，4-第三方付(仅SF支持) |
||
|
MonthCode |
String(20) |
C |
月结编号 |
||
|
ExpType |
Int(2) |
R |
详细快递类型参考《快递公司快递业务类型.xlsx》 |
||
|
IsReturnSignBill |
Int(1) |
O |
是否要求签回单 0-不要求，1-要求 |
||
|
Receiver |
Company |
String(30) |
O |
收件人公司 |
|
|
Name |
String(30) |
R |
收件人 |
||
|
Tel |
String(20) |
R |
电话与手机，必填一个 |
||
|
Mobile |
String(20) |
||||
|
PostCode |
String(10) |
C |
收件地邮编(ShipperCode为EMS、YZPY、YZBK时必填) |
||
|
ProvinceName |
String(20) |
R |
收件省 (如广东省，不要缺少“省”；如是直辖市，请直接传北京、上海等； 如是自治区，请直接传广西壮族自治区等)
|
||
|
CityName |
String(20) |
R |
收件市(如深圳市，不要缺少“市； 如是市辖区，请直接传北京市、上海市等”) |
||
|
ExpAreaName |
String(20) |
R |
收件区/县(如福田区，不要缺少“区”或“县”) |
||
|
Address |
String(100) |
R |
收件人详细地址 |
||
|
Sender |
Company |
String(30) |
O |
发件人公司 |
|
|
Name |
String(30) |
R |
发件人 |
||
|
Tel |
String(20) |
R |
电话与手机，必填一个 |
||
|
Mobile |
String(20) |
||||
|
PostCode |
String(10) |
C |
发件地邮编(ShipperCode为EMS、YZPY、YZBK时必填) |
||
|
ProvinceName |
String(20) |
R |
发件省 (如广东省，不要缺少“省”； 如是直辖市，请直接传北京、上海等； 如是自治区，请直接传广西壮族自治区等) |
||
|
CityName |
String(20) |
R |
发件市(如深圳市，不要缺少“市； 如是市辖区，请直接传北京市、上海市等”) |
||
|
ExpAreaName |
String(20) |
R |
发件区/县(如福田区，不要缺少“区”或“县”) |
||
|
Address |
String(100) |
R |
发件人详细地址（实际取件） |
||
|
SenderShowAddress |
String(100) |
O |
发件人详细地址 |
||
|
StartDate |
Date |
O |
上门揽件时间段，格式：YYYY-MM-DD HH24:MM:SS |
||
|
EndDate |
|||||
|
Weight |
Double(10,3) |
O |
包裹总重量kg |
||
|
Quantity |
Int(2) |
R |
包裹数，一个包裹对应一个运单号，如果是大于1个包裹，返回则按照子母件的方式返回母运单号和子运单号 |
||
|
Volume |
Double(20,3) |
O |
包裹总体积m3 |
||
|
Remark |
String(60) |
O |
备注 |
||
|
AddService
|
Name |
String(20) |
O |
||
|
Value |
String(30) |
O |
增值服务值 |
||
|
CustomerID |
String(30) |
O |
客户标识 |
||
|
Commodity |
GoodsName |
String(100) |
R |
商品名称 |
|
|
GoodsCode |
String(20) |
O |
商品编码 |
||
|
Goodsquantity |
Int(5) |
O |
商品件数 |
||
|
GoodsPrice |
Double(10) |
O |
商品价格 |
||
|
GoodsWeight |
Double(10,3) |
O |
商品重量kg |
||
|
GoodsDesc |
String(50) |
O |
商品描述 |
||
|
GoodsVol |
Double(15,3) |
O |
商品体积m3 |
||
|
PackingType |
Int(2) |
C |
包装类型(快运字段)默认为0； 0-纸，1-纤，2-木，3-托膜，4-木托，99-其他 |
||
|
DeliveryMethod |
Int(1) |
C |
送货方式(快运字段)默认为0； 0-自提，1-送货上门（不含上楼），2-送货上楼 |
||
请求示例:
|
{ "OrderCode": "012657018199", "ShipperCode": "SF", "PayType": 1, "MonthCode": "1234567890", "ExpType": 1, "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" " CustomerID ": "1234567890" } ], "Weight": 1.0, "Quantity": 1, "Volume": 0.0, "Remark": "小心轻放" } |
返回参数
|
名称 |
类型(字符长度) |
是否必须 |
描述 |
|
EBusinessID |
String(10) |
R |
用户ID |
|
Order.OrderCode |
String(30) |
R |
订单编号 |
|
Order.KDNOrderCode |
String(30) |
R |
快递鸟订单编号 |
|
Order.ShipperCode |
String(10) |
R |
快递公司编码 |
|
Order.LogisticCode |
String(30) |
O |
快递单号 |
|
Success |
Bool(10) |
R |
成功与否(true/false) |
|
ResultCode |
String(5) |
R |
|
|
Reason |
String(50) |
O |
失败原因 |
|
UniquerRequestNumber |
String(50) |
R |
唯一标识 |
返回示例:
|
{ "EBusinessID": "1237100", "Success": true, "Order": { "OrderCode": "012657018199", "KDNOrderCode": "KDN012657018199", " ShipperCode ": " SF ", " LogisticCode ": "615123456789" }, "ResultCode": "100", "Reason": "" } |
提供源码下载：
https://download.csdn.net/download/yanghanwen/12139326
调用第三方物流接口，替换自己的key就能直接使用，主要实现了物流在线轨迹查询，订单订阅，轨迹推送，支持500多家的快递查询接口，包括主流的四通一达，支持上门取件服务，其他接口调用，修改调用指令和参数就能实现。
演示截图：
