Skip to main content
此页面由英文翻译而成。英文版为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。

​
核心概念

本页面说明 Flex Forward API 的关键概念 — 资源之间的关系、标签的生命周期，以及追踪数据如何在物流商之间规范化。

​
资源

API 管理三种相关资源，全部通过标签 ID（UUID）关联： 从 POST /labels 返回的标签 ID 是所有操作中使用的主键。没有单独的追踪 ID — 追踪始终通过标签 ID 访问。

​
标签生命周期

标签会经历以下状态：
1

已创建

标签请求已被物流商接受。响应包含 courierOrderNumber、courierTrackingNumber 和标签 id。标签文件可供获取。
2

文件可用

可通过 GET /labels/{id} 下载运单的 PDF 或 PNG。打印并贴附在货件上。文件 URL 为永久性，不会过期。支持的格式为 PDF 和 PNG。
3

追踪进行中

物流商扫描包裹后，可通过 GET /tracking/{id} 获取追踪数据。追踪数据从物流商近实时获取。追踪状态会经过 InfoReceived、InTransit、Delivered 等阶段。规范化的状态标签可能会随着额外物流商数据的获取而演进。
如果物流商拒绝请求，标签会以 status: failed 保存，并包含物流商的错误详情。详情请参阅错误处理。

​
追踪状态模型

追踪数据使用基于行业标准的统一状态模型。每个追踪响应包含顶层的 tag 和 subtag，以及代表单个追踪事件的 checkpoints 数组。

​
状态标签

subtag 字段提供更细致的粒度（如 InTransit_001、Exception_002）。高级状态逻辑使用 tag，详细状态显示使用 subtag。

​
检查点

每个检查点代表一个追踪事件：
检查点以最新事件排在最前面（反向时间顺序）。最早的事件出现在数组的最后。

​
物流商规范化

每个物流商都有自己的 API 格式、状态码和错误惯例。Flex Forward 规范化了这些差异：
  • 统一请求格式 — 无论物流商如何，都提交相同的 JSON 结构。物流商特定的细节在内部处理。
  • 统一响应格式 — 接收包含 id、status、courierOrderNumber、courierTrackingNumber 和（失败时）error 的一致标签响应。
  • 统一追踪 — 不同物流商的追踪事件映射到相同的状态标签分类体系和检查点格式。
这意味着您的集成代码不需要处理物流商特定的逻辑。当新的物流商启用时，您现有的集成无需修改即可运作。

​
物流商与产品代码

每个标签请求需要 courier 代码和 productCode。调用 GET /couriers 以列出您账户可用的有效物流商代码，然后在创建标签时将其中一个返回的 code 值作为 courier 传入。 选择物流商后，使用该物流商代码调用 GET /products，以列出您的配送路线可用的产品代码。serviceCode 字段为可选，在可用时启用特定的服务等级。

​
地址参考数据

地址字段需要标准化的代码：
  • countryCode — ISO 3166-1 alpha-2 国家代码（如 US、JP、CN、GB、DE）
  • state — 州或省代码，对于需要州级地址的国家为必填（如美国的 CA、NY、TX）
如需完整的美国州代码列表，请参阅 州代码参考。

​
集成流程

典型的集成顺序：
三个 GET 操作都使用从最初 POST /labels 调用返回的相同标签 id。不需要管理文件和追踪的单独标识符。
追踪数据从物流商实时获取。对于尚未被物流商扫描的货件，追踪响应可能会返回无检查点的 Pending 或 InfoReceived 状态。