开始接入

M Express 是服务端到服务端的集成。请始终使用生产 API 基础地址进行构建和测试：

https://mexpress.nz/api/v1

文档地址不是 API 地址

https://docs.mexpress.nz 只承载本指南。API 请求应发送到 https://mexpress.nz/api/v1。

建议按此顺序实现

1. 先读取追踪状态。 用一个已知的 tracking_number 调用追踪 API， 同时处理 200 与 404。
2. 让 webhook 可安全重试。 保留原始请求体、验签、持久记录 event_id，并尽快返回 2xx。
3. 准备运行保障。 上线前确认重试策略、密钥存放、告警和接收端恢复路径。

只在服务端保存集成密钥

webhook 签名密钥是生产机密。将其保存在服务端机密存储中，只供可信后端代码使用，并从日志中 脱敏。

不要把它们嵌入浏览器或移动端代码、源码仓库或支持截图。一旦怀疑泄露，立即停止使用受影响的值， 申请轮换后再继续集成。

测试你负责的结果

场景	预期处理
已知追踪号	读取安全的 200 状态投影。
未知或不可用的追踪号	将 404 统一处理为一个面向用户的中性结果。
追踪限流	按 Retry-After 指示的时间等待后再重试。
有效 webhook	校验未改动的原始请求体、记录事件并确认。
重复或乱序 webhook	每个 event_id 只产生一次业务处理；按 scanned_at 排列客户可见状态。

上线检查清单

• [ ] 每个 API 请求均以 https://mexpress.nz/api/v1 开头。
• [ ] webhook 签名密钥只保存在服务端机密存储中。
• [ ] 追踪轮询遵守 Retry-After、退避与随机抖动。
• [ ] webhook 在返回正常大小的 2xx 前，已持久记录 event_id。
• [ ] 监控能报告 API 失败和 webhook 验签失败，但不会记录密钥材料。

常见误区

应当这样做	不要这样做
请求 mexpress.nz/api/v1	向 docs.mexpress.nz 发送 API 请求
对原始字节验签	解析 JSON 后重新序列化再验签
将 404 作为一个中性结果	向终端用户泄露不可用原因
快速 2xx 后异步处理	等待慢速下游任务才响应

下一步

按需继续阅读追踪 API或Webhooks。