上一篇文章我们介绍了上门取件服务的重要性,这次我们来聊聊如何对接取件接口。
前期工作就不多说了,快递鸟官网注册,获取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": "" } |
提供源码下载:
调用第三方物流接口,替换自己的key就能直接使用,主要实现了物流在线轨迹查询,订单订阅,轨迹推送,支持500多家的快递查询接口,包括主流的四通一达,支持上门取件服务,其他接口调用,修改调用指令和参数就能实现。
演示截图: