快递100 订阅推送对接笔记：param 字段、返回码与 md5(param+salt) 验签
对接快递100 的快递信息订阅推送，链路分三段：订阅接口提交单号 → 快递100 跟踪运单 → 状态变化时回调你方接口，直到单号生命周期结束（一般以“已签收”为准）。
订阅请求地址：https://poll.kuaidi100.com/poll，POST，Content-Type: application/x-www-form-urlencoded。
订阅请求参数
body 只有两个顶层字段：schema（json 默认 / xml）和 param（JSON 字符串）。
param 内字段：
| 字段 | 必填 | 说明 |
|---|---|---|
company | 是 | 快递公司编码，一律小写，严格对齐编码表，如 yuantong、zhongtong、ems |
number | 是 | 单号 6–32 字符，允许 -，其他字符会导致订阅失败 |
from / to | 否 | 中文省市区。填了有助于签收状态判断，to 还影响到达目的地后的监控频率；resultv2=8（时效预测）时 to 必填 |
key | 是 | 授权码，企业版获取 |
parameters.callbackurl | 是 | 回调地址，默认仅支持 http，需要 https 需联系快递100 技术人员处理 |
parameters.salt | 否 | 签名用随机字符串，不能含空格和不可见字符；建议同一单重复订阅时保持一致，否则前后签名对不上 |
parameters.resultv2 | 否 | 空=关闭；1=行政区域解析+轨迹状态名称；4=在 1 基础上加高级状态名称/状态值/出发目的当前城市；8=在 4 基础上加预计到达时间和预计轨迹 |
parameters.autoCom | 否 | 1 开启智能判断单号所属公司，开启后 company 必须留空 |
parameters.interCom | 否 | 1 走国际版，仅邮政体系国际单、EMS 等 |
parameters.phone | 否 | 收发件人手机号，顺丰速运、顺丰快运、中通快递必填；电商虚拟号取 - 后四位 |
departureCountry / departureCom / destinationCountry / destinationCom | 否 | 国际版使用 |
一次请求只能提交一个单号。单量大时适度并发，尽量不要集中提交。
订阅返回与返回码
{"result": true, "returnCode": "200", "message": "提交成功"}
返回码含义：
200提交成功。500服务器错误。服务器间隙或临时异常；参数不规范（如快递公司写错）也会报这个。501重复订阅。该单已订阅成功且仍在跟踪中，要等status=abort或shutdown后隔半小时再提交。502提交内容含敏感关键字被安全防护拦截（回调地址或内容含敏感词）。600不是合法订阅者：授权 Key 出错，或账号无可用单量。601KEY 已过期，需充值。700不支持的快递公司，编码有误。701订阅数据有错误（不支持的快递公司、单号为空、超长）或回调地址错误。702识别不到单号对应快递公司（编码错或无可用单量）。
同一快递公司同一单号每月最大订阅 4 次，超过会报重复订阅；40 天内重复订阅不重复收费。
推送请求（打到你的 callbackurl）
同样是 POST form，只有两个字段：sign 和 param。
param 中的字段：
status：监控状态，polling监控中 /shutdown结束（已签收）/abort中止 /updateall重新推送。billstatus：已弃用，忽略。message：监控状态相关消息，如“3天查询无记录”“60天无变化”。顺丰、中通手机号传错会通过此字段返回异常。autoCheck：0表示推送信息对应你提交的原始公司编码，1表示对应快递100 纠正后的编码。comOld/comNew：原始编码 / 纠正后编码。lastResult：message、state、status、condition、ischeck、com、nu、data[]、routeInfo、isLoop。state：0 在途、1 揽收、2 疑难、3 签收、4 退签、5 派件、8 清关、14 拒签。ischeck：0 未签收、1 已签收。data[]元素含context/ftime/time/status/statusCode/areaCode/areaName/areaCenter/location/areaPinYin。routeInfo含from/cur/to。resultv2=8时额外有arrivalTime、totalTime、remainTime、predictedRoute。
签名规则：salt 不为 null 时推送带 sign，算法为 md5(param + salt)，结果转 32 位大写；salt 为空串时推送同样会带 sign，不验会报签名错误。
下面是依据文档签名规则写的 PHP 回调验签示例，未在生产环境实测：
true, 'returnCode' => '200', 'message' => '成功']);
Go 侧验签片段，同样未在生产环境实测：
// 依据文档签名规则编写，未在生产环境实测
func verifySign(param, salt, sign string) bool {
sum := md5.Sum([]byte(param + salt))
expect := strings.ToUpper(hex.EncodeToString(sum[:]))
return subtle.ConstantTimeCompare([]byte(expect), []byte(sign)) == 1
}
回调应答
必须返回：
{"result": true, "returnCode": "200", "message": "成功"}
xml 模式下对应：
true200成功
先把数据落库再应答，其他字段会被忽略。
如果提交回调地址失败，30 分钟后重新回调，3 次仍失败自动放弃这次更新推送，等下一次状态更新再推。status=abort（3 天查询无记录 / 60 天无变化）这类推送也必须返回成功应答，否则同样会重试。
跟踪节奏与超时
订阅成功后一般 15 分钟内做第一次监控，有跟踪信息就推送；之后一般每 2–4 小时监控一次，并按单号状态调整。查询集中在早 8 点到晚 22 点，凌晨的变化在 7–8 点统一同步。
连续 3 天查不到跟踪信息：先判断公司编码是否正确。
- 编码正确：推
autoCheck=0、comOld/comNew为空、message="3天查询无记录"、status=abort，此时重新提交订阅。 - 编码错误：快递100 用正确编码 + 原单号重新订阅监控，并推
status=abort、autoCheck=0、comNew=正确编码。此时不要再重订，改公司编码，或新增一条comNew+ 原单号的运单。之后若收到status=polling且autoCheck=1，这条是纠正后的跟踪信息，应保存。
有轨迹后某节点起连续 10 天无变化，查询频率降为每天一次，直到第 60 天推 status=abort、message 含“60天”，之后停止跟踪。
常见问题
- 验证签名失败：
sign不是md5(param+salt)的大写，或者salt与订阅时不一致（salt为空串时也要按空串算）。 - 重复订阅 501：单还在
polling，一单只需订阅一次。 - 非法 IP：回调地址或调用来源不在白名单内。
- 收不到推送：先看管理后台订阅是否成功；账号是否因刷单被关闭；单号本身 3 天无揽收会被“超时关闭”，需按 abort 重订（40 天内不重复收费）。
HTTP_CLIENT_ERROR: Received fatal alert: protocol_version：对方 TLS 版本过低，回调地址需升级 TLS。- 回调地址变更：变更后要重新订阅才会推到新地址。
- 重开、重推、关闭：管理后台可对订阅记录操作，重推用于补发历史推送。
- 快递100 回调会拦截部分敏感字段，自定义参数建议放在 callbackurl 的 query 里。
文档与 SDK
- 接口文档：https://api.kuaidi100.com/document/60509440a62a19500e1987b7
- Java Demo（含 Subscribe 与回调参考实现）：https://github.com/kuaidi100-api/java-demo
快递公司编码表、API 调试工具在文档中心。