> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 核心概念

> Flex Forward API 的关键概念与心智模型

<Note>
  此页面由英文翻译而成。[英文版](/introduction)为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。
</Note>

# 核心概念

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

## 资源

API 管理三种相关资源，全部通过**标签 ID**（UUID）关联：

| 资源   | 端点                   | 说明                  |
| ---- | -------------------- | ------------------- |
| 标签   | `POST /labels`       | 提交给物流商的配送标签请求       |
| 标签文件 | `GET /labels/{id}`   | 标签的可打印运单（PDF 或 PNG） |
| 追踪   | `GET /tracking/{id}` | 标签的实时配送追踪数据         |

从 `POST /labels` 返回的标签 ID 是所有操作中使用的主键。没有单独的追踪 ID — 追踪始终通过标签 ID 访问。

## 标签生命周期

标签会经历以下状态：

```mermaid theme={null}
stateDiagram-v2
    [*] --> Created : Courier accepts
    [*] --> Failed : Courier rejects
    Created --> DocumentAvailable : Label document ready
    DocumentAvailable --> TrackingActive : Courier scans package
    TrackingActive --> Delivered : Shipment delivered
    TrackingActive --> Exception : Issue during transit
```

<Steps>
  <Step title="已创建">
    标签请求已被物流商接受。响应包含 `courierOrderNumber`、`courierTrackingNumber` 和标签 `id`。标签文件可供获取。
  </Step>

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

  <Step title="追踪进行中">
    物流商扫描包裹后，可通过 `GET /tracking/{id}` 获取追踪数据。追踪数据从物流商近实时获取。追踪状态会经过 `InfoReceived`、`InTransit`、`Delivered` 等阶段。规范化的状态标签可能会随着额外物流商数据的获取而演进。
  </Step>
</Steps>

如果物流商拒绝请求，标签会以 `status: failed` 保存，并包含物流商的错误详情。详情请参阅[错误处理](/zh-Hans/error-handling#下游物流商错误502)。

## 追踪状态模型

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

### 状态标签

| 标签             | 含义                    |
| -------------- | --------------------- |
| `Pending`      | 标签已创建但尚未被物流商接收        |
| `InfoReceived` | 物流商已接收配送信息            |
| `InTransit`    | 货件运送中                 |
| `Delivered`    | 货件已送达                 |
| `Exception`    | 运送期间发生问题（如：派送失败、海关扣留） |
| `Cancelled`    | 配送已取消                 |
| `Unknown`      | 无法判定状态                |

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

### 检查点

每个检查点代表一个追踪事件：

```json theme={null}
{
  "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`。调用 [`GET /couriers`](/zh-hans/api-reference/couriers/list-couriers) 以列出您账户可用的有效物流商代码，然后在创建标签时将其中一个返回的 `code` 值作为 `courier` 传入。

| 物流商        | 代码           | 产品代码      | 说明     |
| ---------- | ------------ | --------- | ------ |
| YunExpress | `yunexpress` | `HKMUZXR` | 标准跨境电商 |

选择物流商后，使用该物流商代码调用 [`GET /products`](/zh-hans/api-reference/products/list-products)，以列出您的配送路线可用的产品代码。`serviceCode` 字段为可选，在可用时启用特定的服务等级。

## 地址参考数据

地址字段需要标准化的代码：

* **`countryCode`** — ISO 3166-1 alpha-2 国家代码（如 `US`、`JP`、`CN`、`GB`、`DE`）
* **`state`** — 州或省代码，对于需要州级地址的国家为必填（如美国的 `CA`、`NY`、`TX`）

<Note>
  如需完整的美国州代码列表，请参阅 [州代码参考](https://apidocs.returnhelper.com/reference/supported-states)。
</Note>

## 集成流程

典型的集成顺序：

```
1. 身份验证      →  在所有请求中包含 Bearer 令牌
2. 创建标签      →  POST /labels  →  接收标签 ID + 追踪号码
3. 获取文件      →  GET /labels/{id}  →  下载 PDF/PNG
4. 追踪货件      →  GET /tracking/{id}  →  轮询状态更新
```

三个 GET 操作都使用从最初 `POST /labels` 调用返回的相同标签 `id`。不需要管理文件和追踪的单独标识符。

<Note>
  追踪数据从物流商实时获取。对于尚未被物流商扫描的货件，追踪响应可能会返回无检查点的 `Pending` 或 `InfoReceived` 状态。
</Note>