快递公司接入快递100订阅推送接口
POST
http://www.xxxx.com/track/order.do
一、名词解释
二、订阅请求
param数据结构
名称 | 是否必填 | 类型 | 说明 |
---|---|---|---|
company | 是 | string | 快递公司编码,少量快递公司支持多品牌 |
code | 是 | string | 快递单号 |
operator | 是 | string | 操作类型,order表示订阅,repush表示请求快递公司发起一次全量重推 |
callback | 是 | string | 回调地址,用于接收推送数据,在推送时需提供,不多于32字节的文本 |
< form action = " http://www.xxxx.com/track/order.do "
method = "post" >
<
input type = "hidden"
name = "param"
value = "json参数" / >
<
input type = "hidden"
name = "sign"
value = "md5" / >
<
input type = "hidden"
name = "customer"
value = "kuaidi100" / >
<
/form>
{
// 快递公司编码,少量快递公司支持多品牌
"company": "xxxx",
//订阅的快递单号
"code": "12345678",
//操作:order表示订阅,repush表示请求快递公司发起一次全量重推
"operator": "order",
// 回调参数,快递100需要的附加参数,在推送时需提供,不多于32字节的文本
"callback": "123468121"
}
三、订阅应答
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
result | boolean | 提交结果 | true提交成功,false失败 |
returnCode | string | 返回编码 | |
message | string | 返回报文描述 |
{
//订阅的结果:true表示成功,false表示失败
"result": "true",
//推送的结果状态
"returnCode": "200",
//对应状态的文本描述
"message": "成功",
}
信息代码含义
信息代码 | 信息内容描述 | 快递100需要做的操作 |
---|---|---|
200 | 成功 | |
400 | 数据不完整 | 补充数据,重新订阅 |
500 | 请求格式错误 | 程序有问题,需要调整 |
501 | 服务器错误 | 30分钟后尝试 |
502 | 重复订阅 | 理解为订阅成功 |
503 | 验证签名失败 | 请使用正确的KEY |
504 | 单号错误 | 更正单号 |
507 | 查询异常 |
四、推送请求
请求头
名称 | 类型 | 默认值 |
---|---|---|
Content-Type | string | application/x-www-form-urlencoded |
请求体
名称 | 是否必填 | 类型 | 说明 |
---|---|---|---|
sign | 是 | string | 签名,用于验证身份,按MD5 (param +t+key)的顺序进行MD5加密,不需要加上“+”号 |
company | 是 | string | 快递公司编码 |
param | 是 | param | 由其他字段拼接 |
param数据结构
名称 | 是否必填 | 类型 | 说明 |
---|---|---|---|
watchStatus | 是 | string | 包裹跟踪状态:normal:跟踪,stop:结束,abort:中止(3天无结果) |
operation | 是 | string | 推送操作状态:append:扩展,override:覆盖 |
status | 是 | string | 包裹运输状态,0在途、1揽收、2疑难、3签收、4退签、5派件、6退回、7转单、8结算 |
company | 是 | string | 快递公司编码 |
code | 是 | string | 快递单号 |
callback | 是 | string | 快递公司的订阅请求地址 |
Θdetail | |||
id | 是 | string | 标识路由状态的顺序ID |
context | 是 | string | 快递最新路由信息 |
time | 是 | string | 当前路由信息时间:yyyy-mm-dd hh:mm:ss |
location | 是 | string | 包裹位置:使用正确的中文行政区划地名,最好包含省、地、县 |
operator | 是 | string | 操作人 |
tel | 是 | string | 操作人电话 |
< form action = " http://www.kuaidi100.com/callback.do"
method = "post" >
<
input type = "hidden"
name = "param"
value = "json参数" / >
<
input type = "hidden"
name = "sign"
value = "md5" / >
<
input type = "hidden"
name = "company"
value = "xxxx" / >
<
/form>
{
// 包裹跟踪状态:normal:跟踪,stop:结束,abort:中止(3无结果)。
"watchStatus": "normal",
// 推送操作状态:append:扩展,override:覆盖
"operation": "append",
// 包裹运输状态,0在途、1揽收、2疑难、3签收、4退签、5派件、6退回、7转单、8结算
"status": 0,
// 快递公司编码,少量快递公司支持多品牌
"company": "xxxx",
// 运单号
"code": "123456789012",
// 回调参数,源自订阅请求
"callback": "123468121", //这么的Callback值为快递公司的订阅请求地址
// 路由信息
"detail": [{
// 标识路由状态的顺序ID
"id": 5,
// 最新路由信息
"context": "装件入车",
// 原先的description会被服务器拦截,所以统一换成context
// 时间:yyyy-mm-ddhh:mi:ss
"time": "2012-08-28 17:22:33",
// 包裹位置:使用正确的中文行政区划地名,最好包含省、地、县。
"location": "湖北,武汉,汉正街",
// 操作人(可选)
"operator": "张三",
// 操作人电话(可选)
"tel": "13877777777"
}, {
// 标识路由状态的顺序ID
"id": 6,
// 最新路由信息
"context": "发往广东深圳",
// 时间:yyyy-mm-ddhh:mi:ss
"time": "2012-08-28 17:33:19",
// 包裹位置:使用正确的中文行政区划地名,最好包含省、地、县。
"location": "湖北,武汉,汉正街",
// 操作人(可选)
"operator": "张三",
// 操作人电话(可选)
"tel": "13877777777"
}]
}
状态值 | 名称 | 含义 |
---|---|---|
0 | 在途 | 快件处于运输过程中 |
1 | 揽件 | 快件已由快递公司揽收 |
2 | 疑难 | 快递100无法解析的状态,或者是需要人工介入的状态,比方说收件人电话错误 |
3 | 签收 | 正常签收 |
4 | 退签 | 货物退回发货人并签收 |
5 | 派件 | 货物正在进行派件 |
6 | 退回 | 货物正处于返回发货人的途中 |
7 | 转投 | 货物已转交给其他快递公司代为投递 |
8 | 结算 | COD货到付款完成结算 |
五、推送应答
字段 | 类型 | 说明 | 备注 |
---|---|---|---|
result | boolean | 提交结果 | true提交成功,false失败 |
returnCode | string | 返回编码 | |
message | string | 返回报文描述 |
{
//订阅的结果:true表示成功,false表示失败
"result": "true",
//推送的结果状态
"returnCode": "200",
//对应状态的文本描述
"message": "成功",
}
信息代码含义
信息代码 | 信息内容描述 | 快递公司需要做的操作 |
---|---|---|
200 | 成功 | |
300 | 用户取消订阅 | 取消推送 |
400 | 数据不完整 | 请以override模式重发完整结果 |
500 | 请求格式错误 | 程序有问题,需要调整 |
501 | 服务器错误 | 30分钟后尝试 |
六、Abort推送请求
名称 | 是否必填 | 类型 | 说明 |
---|---|---|---|
watchStatus | 是 | string | 包裹跟踪状态:normal:跟踪,stop:结束,abort:中止(3天无结果) |
company | 是 | string | 快递公司编码 |
code | 是 | string | 快递单号 |
callback | 是 | string | 回调地址 |
reasonCode | 是 | string | 推送原因代码 |
reasonMessage | 是 | string | 推送原因消息说明 |
{
"watchStatus": "abort",
"company": "xxxx",
"code": "123456789012",
"callback": "123468121",
"reasonCode": "123468121",
"reasonMessage": "123468121",
}
七、Abort推送应答
八、Stop推送请求
名称 | 是否必填 | 类型 | 说明 |
---|---|---|---|
watchStatus | 是 | string | 包裹跟踪状态:normal:跟踪,stop:结束,abort:中止(3天无结果) |
company | 是 | string | 快递公司编码 |
code | 是 | string | 快递单号 |
callback | 是 | string | 回调地址 |
reasonCode | 是 | string | 推送原因代码 |
reasonMessage | 是 | string | 推送原因消息说明 |
{
"watchStatus": "stop",
"company": "xxxx",
"code": "123456789012",
"callback": "123468121",
"reasonCode": "123468121",
"reasonMessage": "123468121",
}
九、Stop推送应答
十、补充说明
字符集问题
全量推送与增量推送问题
推送失败的处理
系统维护约定
性能问题
呆滞单处理
关于repush
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location --request POST 'http://www.xxxx.com/track/order.do' \
--data-urlencode 'key=' \
--data-urlencode 'customer=' \
--data-urlencode 'sign=' \
--data-urlencode 'param='
响应示例响应示例
{}
请求参数
Body 参数application/x-www-form-urlencoded
key
string
必需
customer
string
必需
sign
string
必需
param
string
由其他字段拼接
返回响应
修改于 2022-12-20 09:38:37