此页面由英文翻译而成。英文版为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。
核心概念
本页面说明 Flex Forward API 的关键概念 — 资源之间的关系、标签的生命周期，以及追踪数据如何在物流商之间规范化。资源
API 管理四种相关资源，全部通过标签 ID（UUID）关联：
从
POST /labels 返回的标签 ID 是所有操作中使用的主键。GET /labels/{id} 和 GET /tracking/{id} 都接受标签 UUID 或您的 customerOrderNumber 作为路径参数。没有单独的追踪 ID。GET /orders/{orderId} 仅接受标签 UUID；订单与标签共用同一个 id。
物流商的标识符（
courierOrderNumber、courierTrackingNumber）不能作为 {id} 使用。传入物流商追踪号会返回 404 Label not found。请保存标签 UUID，或使用您自己的 customerOrderNumber。客户订单号
order.customerOrderNumber 在创建标签时为可选字段。若提供，必须在账户内唯一，长度为 1–40 个字符，且只能使用 ASCII 字母（A–Z、a–z）、数字、-、_。区分大小写。空格、逗号及其他字符会被拒绝。
若省略该字段，API 会生成一个订单号。请保存返回的 customerOrderNumber 或标签 id；不要假设生成的订单号等同于标签 UUID。两者都可用于获取文件和追踪信息。
FlexForward 会将 {clientCode}-{customerOrderNumber} 作为客户参考发送给物流商。物流商会在支持的情况下将该参考打印在标签上。查询时请使用 API 返回的、不带前缀的 customerOrderNumber。
标签生命周期
标签会经历以下状态：1
已创建
标签请求已被物流商接受。响应包含标签
id 和 courierOrderNumber。courierTrackingNumber 此时通常为 null，由末端配送商稍后分配。标签文件可供获取。2
文件可用
可通过
GET /labels/{id} 下载文件。创建时可将 label.format 设为 PDF 或 PNG，省略时使用 PDF。响应中的 labelFormat 会是 pdf 或 png。文件 URL 为短期链接，需要时请重新获取。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 字段为可选，在可用时启用特定的服务等级。
该目录为全局性质。代码列示于目录中，并不代表您的账户已针对该物流商或路线启用；若您的账户尚未配置该物流商的配送账户，POST /labels 将返回 404（Shipping account not found）。
地址参考数据
地址字段需要标准化的代码：countryCode— ISO 3166-1 alpha-2 国家代码（如US、JP、CN、GB、DE）state— 州或省代码，对于需要州级地址的国家为必填（如美国的CA、NY、TX）
如需完整的美国州代码列表，请参阅 州代码参考。
集成流程
典型的集成顺序：POST /labels 调用返回的相同标签 id。不需要管理文件、追踪和订单的单独标识符。
追踪数据从物流商实时获取。对于尚未被物流商扫描的货件，追踪响应可能会返回无检查点的
Pending 或 InfoReceived 状态。