> ## 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.

# 快速入门

> 几分钟内创建您的第一个配送标签

# 快速入门

本指南将引导您完成创建第一个配送标签、获取标签文件以及追踪货件的流程。

## 前提条件

* API 令牌（获取方式请参阅[身份验证](/zh-Hans/authentication)）
* `curl` 或任何 HTTP 客户端
* 开发环境基础 URL：`https://sandbox.flexforward.com`

<Note>
  测试请使用开发环境。该环境连接至物流商的沙盒服务，不会创建实际的配送。
</Note>

## 步骤 1：身份验证

在每个请求的 `Authorization` 头部中包含您的 Bearer 令牌：

```
Authorization: Bearer YOUR_API_TOKEN
```

令牌最佳实践与错误响应请参阅[身份验证](/zh-Hans/authentication)页面。

## 步骤 2：创建标签

发送包含配送信息的 `POST /labels` 请求。`idempotencyKey` 确保重试相同的请求不会创建重复标签。

<Note>
  **最低限必填字段：** 需要 `idempotencyKey`、`courier`、`service.productCode`、`shipment.shipTo`（包含 `firstName` 的 contact 以及包含 `countryCode`、`city`、`postalCode`、`streetLines` 的 address），以及包含 `weight` 和至少一个 item（`descriptionEn`、`quantity`、`unitPrice`、`unitWeight`）的 parcel。`shipment.shipFrom` 字段在特定物流商和配送路线中为必填 — 请在上线期间向 Flex Forward 团队确认您的需求。
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://sandbox.flexforward.com/labels \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "idempotencyKey": "quickstart-test-001",
      "courier": "yunexpress",
      "service": {
        "productCode": "HKMUZXR"
      },
      "shipment": {
        "shipFrom": {
          "contact": {
            "firstName": "Test",
            "lastName": "Sender",
            "phone": "+81-90-1234-5678"
          },
          "address": {
            "countryCode": "JP",
            "city": "Tokyo",
            "postalCode": "100-0001",
            "streetLines": ["1-1 Marunouchi"]
          }
        },
        "shipTo": {
          "contact": {
            "firstName": "Test",
            "lastName": "Recipient",
            "phone": "+1-555-0100"
          },
          "address": {
            "countryCode": "US",
            "city": "Los Angeles",
            "state": "CA",
            "postalCode": "90001",
            "streetLines": ["123 Main St"]
          }
        },
        "parcels": [
          {
            "weight": 0.5,
            "items": [
              {
                "descriptionEn": "T-Shirt",
                "descriptionLocal": "T恤",
                "quantity": 2,
                "unitPrice": { "amount": 25.00, "currency": "USD" },
                "unitWeight": 0.25
              }
            ]
          }
        ]
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://sandbox.flexforward.com/labels', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      idempotencyKey: 'quickstart-test-001',
      courier: 'yunexpress',
      service: {
        productCode: 'HKMUZXR'
      },
      shipment: {
        shipFrom: {
          contact: { firstName: 'Test', lastName: 'Sender', phone: '+81-90-1234-5678' },
          address: { countryCode: 'JP', city: 'Tokyo', postalCode: '100-0001', streetLines: ['1-1 Marunouchi'] }
        },
        shipTo: {
          contact: { firstName: 'Test', lastName: 'Recipient', phone: '+1-555-0100' },
          address: { countryCode: 'US', city: 'Los Angeles', state: 'CA', postalCode: '90001', streetLines: ['123 Main St'] }
        },
        parcels: [{
          weight: 0.5,
          items: [{
            descriptionEn: 'T-Shirt',
            descriptionLocal: 'T恤',
            quantity: 2,
            unitPrice: { amount: 25.00, currency: 'USD' },
            unitWeight: 0.25
          }]
        }]
      }
    })
  });
  const label = await response.json();
  console.log(label.id); // Use this ID for document retrieval and tracking
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://sandbox.flexforward.com/labels',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
      json={
          'idempotencyKey': 'quickstart-test-001',
          'courier': 'yunexpress',
          'service': {
              'productCode': 'HKMUZXR'
          },
          'shipment': {
              'shipFrom': {
                  'contact': {'firstName': 'Test', 'lastName': 'Sender', 'phone': '+81-90-1234-5678'},
                  'address': {'countryCode': 'JP', 'city': 'Tokyo', 'postalCode': '100-0001', 'streetLines': ['1-1 Marunouchi']}
              },
              'shipTo': {
                  'contact': {'firstName': 'Test', 'lastName': 'Recipient', 'phone': '+1-555-0100'},
                  'address': {'countryCode': 'US', 'city': 'Los Angeles', 'state': 'CA', 'postalCode': '90001', 'streetLines': ['123 Main St']}
              },
              'parcels': [{
                  'weight': 0.5,
                  'items': [{
                      'descriptionEn': 'T-Shirt',
                      'descriptionLocal': 'T恤',
                      'quantity': 2,
                      'unitPrice': {'amount': 25.00, 'currency': 'USD'},
                      'unitWeight': 0.25
                  }]
              }]
          }
      }
  )
  label = response.json()
  print(label['id'])  # Use this ID for document retrieval and tracking
  ```
</CodeGroup>

请求成功时，返回 HTTP 201 和标签详情：

```json 201 Created theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
```

响应中的主要字段：

| 字段                      | 说明                                    |
| ----------------------- | ------------------------------------- |
| `id`                    | 标签的 UUID。用于获取文件和追踪。                   |
| `status`                | 成功时为 `created`，物流商拒绝请求时为 `failed`。    |
| `courierOrderNumber`    | 物流商分配的订单号码。                           |
| `courierTrackingNumber` | 物流商分配的追踪号码。                           |
| `error`                 | 成功时为 `null`。失败时包含 `code` 和 `message`。 |

<Warning>
  使用相同的 `idempotencyKey` 重试请求时，API 会返回 HTTP 200 和原始结果，而不会创建重复标签。详情请参阅[幂等性与重试](/zh-Hans/idempotency-and-retries)。
</Warning>

## 步骤 3：获取标签文件

使用前一个响应中的标签 `id` 来获取运单文件：

```bash theme={null}
curl https://sandbox.flexforward.com/labels/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```json 200 OK theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "quickstart-test-001",
  "url": "https://label-documents.example.com/labels/a1b2c3d4.pdf",
  "labelFormat": "pdf"
}
```

从返回的 `url` 下载 PDF 或 PNG 来打印配送标签。

## 步骤 4：追踪货件

使用相同的标签 `id` 来获取追踪信息：

```bash theme={null}
curl https://sandbox.flexforward.com/tracking/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```json 200 OK theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "YT2503010001CN",
  "tag": "InfoReceived",
  "subtag": "InfoReceived_001",
  "subtagMessage": "Shipment information received",
  "slug": "yunexpress",
  "checkpoints": [
    {
      "checkpointTime": "2026-03-15T10:30:00Z",
      "city": "Tokyo",
      "state": "Tokyo",
      "countryRegion": "JP",
      "location": null,
      "message": "Shipment information received",
      "tag": "InfoReceived",
      "subtag": "InfoReceived_001",
      "subtagMessage": "Shipment information received",
      "slug": "yunexpress"
    }
  ]
}
```

`tag` 字段提供货件的概要状态。完整的追踪状态列表请参阅[核心概念](/zh-Hans/core-concepts#追踪状态模型)。

## 成功验证

完成此快速入门后，请验证您可以：

* [ ] 使用 Bearer 令牌成功验证身份
* [ ] 在开发环境创建测试标签
* [ ] 获取可打印的标签文件（PDF 或 PNG）
* [ ] 获取测试标签的规范化追踪更新

## 下一步

<CardGroup cols={3}>
  <Card title="错误处理" icon="triangle-exclamation" href="/zh-Hans/error-handling">
    了解错误响应及如何排查常见问题。
  </Card>

  <Card title="幂等性与重试" icon="rotate" href="/zh-Hans/idempotency-and-retries">
    学习如何安全地重试请求而不创建重复标签。
  </Card>

  <Card title="核心概念" icon="book" href="/zh-Hans/core-concepts">
    了解标签生命周期、追踪模型与物流商规范化。
  </Card>
</CardGroup>