一、拦截改址接口
该接口支持对“运输中且未签收”的快件进行拦截改址处理,方便服务平台、商家、用户在线发起服务直连快递公司。
1.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
1.2 请求地址
https://api.kuaidi100.com/label/order
请求参数:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
method | 是 | string | 业务类型(默认:interceptOrder) |
key | 是 | string | 授权码,请申请企业版获取 |
sign | 是 | string | 32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号secret在企业管理后台查看 |
t | 是 | string | 时间戳如:1576123932000 |
param | 是 | param | 由其他字段拼接 |
param数据结构:
参数名 | 是否必填 | 类型 | 说明 |
---|---|---|---|
kuaidicom | 是 | string | 快递公司的编码,一律用小写字母,请查看参数字典 |
kuaidinum | 是 | string | 快递单号 |
interceptType | 是 | string | 拦截类型,RETURN_SEND_STATION: 退回寄件网点;RETURN_SEND_ADDR: 退回寄件地址;MODIFY_ADDR: 修改地址 |
partnerId | 否 | string | 电子面单客户账户或月结账号,需贵司向当地快递公司网点申请(参考电子面单申请指南); 是否必填该属性,请查看参数字典 |
partnerKey | 否 | string | 电子面单密码,需贵司向当地快递公司网点申请; 是否必填该属性,请查看参数字典 |
net | 否 | string | 收件网点名称,由快递公司当地网点分配。 是否必填该属性,请查看参数字典 |
reason | 否 | string | 拦截原因 |
orderid | 否 | string | 订单id |
ΘrecManInfo | 否 | recMan | 收件人信息,interceptType为MODIFY_ADDR时必填 |
¬name | 是 | string | 收件人姓名 |
¬mobile | 是 | string | 收件人的手机号,手机号和电话号二者其一必填 |
¬tel | 否 | string | 收件人的电话号,手机号和电话号二者其一必填 |
¬printAddr | 是 | string | 收件人所在完整地址,如广东深圳市深圳市南山区科技南十二路2号金蝶软件园B10 |
¬company | 否 | string | 收件人所在公司名称 |
salt | 否 | string | 签名用随机字符串,用于回调拦截结果中验证签名sign |
callbackUrl | 否 | string | 回调地址(中通、极兔、圆通必填,其他快递公司选填,所有快递公司的拦截状态均通过回调返回) |
appKey | 否 | string | 需拦截非快递100渠道下单的中通件时则填入,从中通后台服务商模式下授权至ISV(快递100管家)后可获得,详看中通服务商系统用户接入指南的第四点 |
appSecret | 否 | string | 需拦截非快递100渠道下单的中通件时则填入,从中通后台服务商模式下授权至ISV(快递100管家)后可获得,详看中通服务商系统用户接入指南的第四点 |
1.3 返回结果
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
success | boolean | 提交结果 | true提交成功,false失败 |
code | string | 返回编码 | |
message | string | 返回报文描述 | |
data | string | 相应数据 |
1.4 请求参数示例
method = interceptOrder
key = kytRsteof
sign = 4 BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
"orderId": "",
"kuaidicom": "debangkuaidi",
"kuaidinum": "2222",
"partnerId": "22222",
"partnerKey": "",
"partnerSecret": "",
"interceptType": "MODIFY_ADDR",
"code": "",
"net": "",
"reason": "",
"recManInfo": {
"name": "测试",
"mobile": "138888888888",
"printAddr": "广东深圳市南山区金蝶软件园"
}
}
1.5 返回结果示例
成功示例:
{
"code": 200,
"message": "success",
"time": 0,
"success": true
}
错误示例:
{
"code": 30005,
"message": "快递公司返回异常: 拦截失败运单拦截,计价失败,未查询到该运单信息",
"time": 0,
"success": false
}
返回信息代码含义:
信息代码 | 信息内容描述 | 原因及建议处理方式 |
---|---|---|
-1 | 服务器错误 | 快递100的服务器出现间歇或临时性异常,有时如果因为不按规范提交请求,比如快递公司参数写错等,也会报此错误 |
200 | 提交成功 | 提交成功 |
30001 | 参数错误 | 请根据技术文档请求,注意参数类型及是否必填 |
30002 | 验证签名失败 | 检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号 |
30003 | 账号信息不正确 | 检查key是否正确 |
30004 | 账号单量不足需要充值 | 账号单量不足需要充值 |
30005 | 快递公司返回异常 | 按照描述可以自行检查参数的数据类型是否正确 |
1.7 拦截结果回调
提供统一格式的HTTP POST,并以application/x-www-form-urlencoded格式进行回调请求。
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
sign | string | 签名 | salt值不为null时,回调数据将包含该加密签名,加密方式:md5(param+salt)转大写,param为返回的参数。注意: salt值为空串时,推送的数据也会包含sign,此时可忽略sign的校验。 |
param | string | 回调结果 |
param数据结构:
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
kuaidicom | string | 快递公司编码 | |
kuaidinum | string | 快递单号 | |
interceptResult | int | 拦截结果 | 0-拦截失败,1-拦截成功,2-拦截中,-1-取消拦截 |
interceptResultDesc | string | 拦截结果描述 | 拦截失败时返回 |
returnKuaidiNum | string | 退回单号 | 拦截成功后,产⽣的退回单号(仅拦截成功状态时回传) |
请求参数示例
sign = XXXX
param= {
"interceptResult": 1,
"kuaidicom": "jtexpress",
"kuaidinum": "JT12345675",
"returnKuaidiNum": "JT12345676"
}
当我方调用贵方的回调接口(callbackUrl)时,贵方需要先将我方提交的数据保存至贵方的数据库,接着向我方返回是否成功接收的响应报文及代码(成功状态码:200),即贵公司在成功接收回调的拦截结果后需响应如下内容:
{
"result":true,
"code":"200",
"message":"成功"
}
回调重推机制
如贵方超时未返回或未按规范返回响应报文,我方将向贵方接口重推拦截结果。最大重推次数为8次,间隔时间为1min,1min,1min,2min,3min,7min,15min,30min。
二、支持的快递公司编码
快递公司 | 快递编码 | MODIFY_ADDR (修改地址) | RETURN_SEND_ADDR (退回寄件地址) | RETURN_SEND_STATION (退回寄件网点) |
---|---|---|---|---|
德邦 | debangwuliu | √ | ||
圆通 | yuantong | √ | √ | |
中通 | zhongtong | √ | √ | √ |
极兔 | jtexpress | √ | √ | |
京东 | jd | √ | ||
EMS | ems | √ | ||
邮政快递包裹 | youzhengguonei | √ | ||
邮政电商标快 | youzhengdsbk | √ |