拦截改址接口说明

对运输中且未签收的快件发起拦截改址，支持退回寄件网点、退回寄件地址、修改收件地址三种拦截类型。

一、拦截改址接口

1.1 接口说明

本接口用于对运输中且未签收的快件进行拦截改址处理，支持服务平台、商家、在线用户直接对接快递公司发起拦截申请。

1.2 基本信息

1.3 请求头

本接口无特殊请求头要求，使用标准 HTTP 表单提交即可。

1.4 请求参数

1.4.1 顶层参数

签名算法

按 param + t + key + secret 顺序拼接后进行 MD5 加密，结果转 32 位大写。拼接时不需要加号，secret 在企业管理后台查看。

sign = MD5(param + t + key + secret).toUpperCase()

1.4.2 param 数据结构

中通 appKey / appSecret 获取方式

需通过中通开放平台获取，从中通开放平台后台服务商模式下授权至 ISV（快递100管家）后可获得，参考中通服务商系统用户接入指南第四点。

1.4.3 recManInfo 数据结构

1.5 请求示例

以下为 MODIFY_ADDR（修改地址）场景下的完整请求示例：

POST /label/order HTTP/1.1
Host: api.kuaidi100.com
Content-Type: application/x-www-form-urlencoded

method=interceptOrder
&key=kytRsteof
&sign=4BBDE07660E5EFF90873642CFAE9A8DD
&t=1470304729724
&param={
  "orderId": "",
  "kuaidicom": "debangkuaidi",
  "kuaidinum": "2222",
  "partnerId": "22222",
  "partnerKey": "",
  "interceptType": "MODIFY_ADDR",
  "net": "",
  "reason": "",
  "recManInfo": {
    "name": "测试",
    "mobile": "13888888888",
    "printAddr": "广东深圳市南山区金蝶软件园"
  }
}

1.6 返回参数

1.7 响应示例

1.7.1 成功响应

{
  "code": 200,
  "message": "success",
  "time": 0,
  "success": true
}

1.7.2 失败响应

{
  "code": 30005,
  "message": "快递公司返回异常： 拦截失败运单拦截，计价失败，未查询到该运单信息",
  "time": 0,
  "success": false
}

1.8 错误码

1.9 拦截结果回调

快递100通过回调方式异步通知拦截结果，所有快递公司的拦截状态均通过回调返回。

1.9.1 回调参数

1.9.2 param 数据结构（回调）

1.9.3 回调请求示例

POST {callbackUrl} HTTP/1.1
Content-Type: application/x-www-form-urlencoded

sign=XXXX
&param={
  "interceptResult": 1,
  "kuaidicom": "jtexpress",
  "kuaidinum": "JT12345675",
  "returnKuaidiNum": "JT12345676"
}

1.9.4 回调响应要求

接收方需先将回调数据保存至数据库，再返回成功响应。成功状态码为 200，响应体格式如下：

{
  "result": true,
  "code": "200",
  "message": "成功"
}

1.10 回调重推机制

若接收方超时未返回或未按规范返回响应报文，快递100将自动重推拦截结果。

重推规则： 最大重推 8 次，间隔时间呈递增策略，请确保回调接口稳定可用。

二、取消拦截接口

取消已发起的快递拦截操作，支持取消拦截的快递公司见参数字典。

2.1 接口说明

本接口用于对已发起的拦截申请进行撤销操作，支持部分快递公司取消拦截。

2.2 基本信息

2.3 请求头

本接口无特殊请求头要求，使用标准 HTTP GET 请求即可。

2.4 请求参数

2.4.1 顶层参数

签名算法

按 param + t + key + secret 顺序拼接后进行 MD5 加密，结果转 32 位大写。拼接时不需要加号，secret 在企业管理后台查看。param 为业务参数 JSON 字符串原文，计算签名时须与请求中的 param 逐字符一致（含字段顺序、标点、中文编码）；放入 URL Query 前需做 URL 编码，但签名基于未编码前的原文计算。

sign = MD5(param + t + key + secret).toUpperCase()

2.4.2 param 数据结构

各快递公司必填项说明

快递公司	必填参数
圆通（yuantong）	partnerId、partnerKey
京东（jd）	partnerId
中通（zhongtong）	orderId

其余快递公司按普通参数提交，无额外必填项。

2.5 请求示例

以下为圆通取消拦截场景下的完整请求示例：

GET /label/order?key=your-key&method=cancelInterceptOrder&t=1786955868281&sign=4BBDE07660E5EFF90873642CFAE9A8DD&param={"partnerId":"your-partner-id","partnerKey":"your-partner-key","kuaidicom":"yuantong","kuaidinum":"YT1234567890","remark":"取消退回寄件网点"} HTTP/1.1
Host: api.kuaidi100.com

curl --location -g --request GET \
  'https://api.kuaidi100.com/label/order?key=your-key&method=cancelInterceptOrder&t=1786955868281&sign=4BBDE07660E5EFF90873642CFAE9A8DD&param={"partnerId":"your-partner-id","partnerKey":"your-partner-key","kuaidicom":"yuantong","kuaidinum":"YT1234567890","remark":"取消退回寄件网点"}'

说明： - param 以 JSON 原文置于 URL Query 中，示例使用 -g 关闭 curl 转义；正式调用时建议对 param 做 URL 编码； - sign 基于 param 原文（URL 编码前）计算：MD5(param + t + key + secret) 转大写； - 示例为固定时间戳与签名，仅作格式参考，实际调用需用当前时间戳 t 并重新计算 sign。

2.6 返回参数

2.7 响应示例

2.7.1 成功响应

{
  "code": 200,
  "message": "取消成功",
  "data": {
    "taskId": "xxxxxxxxxxxx"
  }
}

2.7.2 失败响应

{
  "code": 30005,
  "message": "快递公司返回取消失败",
  "data": {
    "taskId": "xxxxxxxxxxxx"
  }
}

2.8 错误码

当外部快递接口返回非 200 业务状态时，code 会透传外部返回的状态码（如 4000 参数错误、500 外部系统异常）。