开始接入

本页把 Tracking、Webhook 和 POD 串成一条服务端实现顺序。你将使用同一组合成 fixture 完成端到端验收。

先锁定地址与密钥边界

API host 是：

https://mexpress.nz/api/v1

https://docs.mexpress.nz 是文档站，不是 API host。所有 API 请求都发送到 mexpress.nz。

Tracking 不需要 Bearer token。Webhook 验签密钥和 POD Bearer token 都由你的后端或机密存储所有者管理。接收端先校验 Content-Type 和全部四个 X-Delivery-Webhook-* headers，再用 X-Delivery-Webhook-Key-Id 查找对应的 signing secret。EVT430 媒体 link 使用组合 Authorization: Bearer <signing_key_id>.<signing_secret> credential；rotation、deactivation 或 deletion 后旧 credential 会失效。不要将它们放进浏览器、移动端、URL、HTML、日志、截图或 CDN。

统一合成 fixture

项目	值
Shipment	MX123456789
Package sequence numbers	1、2
Newer POD batch	11111111-1111-4111-8111-111111111111，2026-07-02T03:04:05.000000Z，sequence 1
Newer location	captured；latitude "-36.8484600"、longitude "174.7633320"、accuracy_meters "4.50"
Older POD batch	22222222-2222-4222-8222-222222222222，2026-07-01T03:04:05.000000Z，sequence 2
Older location	unavailable；latitude、longitude、accuracy_meters 全部为 null
Package UUIDs	33333333-3333-4333-8333-333333333333、44444444-4444-4444-8444-444444444444

POD 只返回符合条件的 POD_COMPLETE batch，并按新到旧返回。可见但仍在处理的 shipment 返回 pod_status: pending 与空的 delivery_batches；不要用空数组或 null 推造不存在的证据。

按这个顺序实现

1. 先做 Tracking。 使用 MX123456789 请求匿名投影，明确区分 200、detail-only 404 和带正整数 Retry-After 的 429。
2. 再做 Webhook。 保留 raw bytes，在 JSON parsing 前验证 timestamp 与 v1= HMAC；先持久化或 claim event_id，然后快速返回正常大小的 2xx。
3. 最后做 POD。 后端使用同一个 pod:read token 读取 manifest 和媒体。只接受由 manifest 派生的 app-owned media key，并验证当前 shipment 的 POD 路径前缀。
4. 加入恢复能力。 让重复事件成为安全 no-op，让慢处理异步执行，让失败响应符合 retryable/permanent 分类。

端到端验收

• [ ] 所有请求都以 https://mexpress.nz/api/v1 开头，文档 host 从未被当作 API host。
• [ ] Tracking 不把 scan code、精确位置或内部字段送到客户界面。
• [ ] 404 产生统一的中性结果；429 至少等待正整数 Retry-After，再使用退避和 jitter。
• [ ] Webhook 在解析前对未改动 raw body 验签，并在副作用前去重 event_id。
• [ ] Webhook 校验 Content-Type 和全部四个 X-Delivery-Webhook-* headers，并按 X-Delivery-Webhook-Key-Id 选择 signing secret。
• [ ] 接收端对重复和可能乱序事件安全；客户历史按 scanned_at 展示。
• [ ] POD 支持 pending、partial、complete，只返回符合条件的完成 batch；pending 使用空的 delivery_batches。captured 只有在三个持久化值都存在、finite 且在既有边界内时返回坐标字符串；缺失、不完整、无效、超界和非 captured location 使用全 null 坐标。
• [ ] POD token 只存在服务端；媒体响应只接受 image/png、image/jpeg、image/svg+xml，并要求去除参数后的上游 Content-Type 与 manifest 一致，同时保留三个安全 header。
• [ ] EVT430 媒体由后端使用当前组合 webhook credential 获取；rotation、deactivation 或 deletion 后旧 credential 被拒绝。
• [ ] 浏览器、URL、HTML、日志、移动端和 CDN 都没有 token 或 raw signature strokes。

继续阅读 Tracking API、Webhooks 和 POD API 获取任务旁的字段 Reference 与可运行示例。