跳转到主要内容

​
核心概念

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

​
资源

API 管理三种相关资源，全部通过标签 ID（UUID）关联：
资源端点说明
标签POST /labels提交给物流商的配送标签请求
标签文件GET /labels/{id}标签的可打印运单（PDF 或 PNG）
追踪GET /tracking/{id}标签的实时配送追踪数据
从 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 数组。

​
状态标签

标签含义
Pending标签已创建但尚未被物流商接收
InfoReceived物流商已接收配送信息
InTransit货件运送中
Delivered货件已送达
Exception运送期间发生问题（如：派送失败、海关扣留）
Cancelled配送已取消
Unknown无法判定状态
subtag 字段提供更细致的粒度（如 InTransit_001、Exception_002）。高级状态逻辑使用 tag，详细状态显示使用 subtag。

​
检查点

每个检查点代表一个追踪事件： 
{
  "checkpointTime": "2026-03-15T14:30:00Z",
  "city": "Tokyo",
  "state": "Tokyo",
  "countryRegion": "JP",
  "location": null,
  "message": "Departed from sorting facility",
  "tag": "InTransit",
  "subtag": "InTransit_001",
  "subtagMessage": "In transit",
  "slug": "yunexpress"
}
检查点以最新事件排在最前面（反向时间顺序）。最早的事件出现在数组的最后。

​
物流商规范化

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

​
物流商与产品代码

每个标签请求需要 courier 代码和 productCode。可用的物流商和产品代码在账户部署时配置。
物流商代码产品代码说明
YunExpressyunexpressYEXP01标准跨境电商
serviceCode 字段为可选，在可用时启用特定的服务等级。如需了解您的物流路线可用的产品代码和服务选项，请联系 Flex Forward 团队。

​
地址参考数据

地址字段需要标准化的代码：
  • countryCode — ISO 3166-1 alpha-2 国家代码（如 US、JP、CN、GB、DE）
  • state — 州或省代码，对于需要州级地址的国家为必填（如美国的 CA、NY、TX）
支持的国家代码和美国州代码的完整参考将在未来版本中提供。

​
集成流程

典型的集成顺序： 
1. 身份验证      →  在所有请求中包含 Bearer 令牌
2. 创建标签      →  POST /labels  →  接收标签 ID + 追踪号码
3. 获取文件      →  GET /labels/{id}  →  下载 PDF/PNG
4. 追踪货件      →  GET /tracking/{id}  →  轮询状态更新
三个 GET 操作都使用从最初 POST /labels 调用返回的相同标签 id。不需要管理文件和追踪的单独标识符。
追踪数据从物流商实时获取。对于尚未被物流商扫描的货件，追踪响应可能会返回无检查点的 Pending 或 InfoReceived 状态。