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

快速入门

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

前提条件

API 密钥与 API 令牌（获取方式请参阅身份验证）
curl 或任何 HTTP 客户端
开发环境基础 URL：https://sandbox.flexforward.com

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

步骤 1：身份验证

在每个请求中同时包含以下两个头部：

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN

认证信息最佳实践与错误响应请参阅身份验证页面。

步骤 2：创建标签

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

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

请使用 GET /couriers 返回的 courier 代码。以下示例使用 yunexpress，但您的有效值取决于账户已启用的物流商。

curl -X POST https://sandbox.flexforward.com/labels \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "idempotencyKey": "unique-key-per-request",
      "courier": "yunexpress",
      "service": {
        "productCode": "HKMUZXR"
      },
      "label": {
        "format": "PDF"
      },
      "units": {
        "weight": "KG",
        "dimension": "CM"
      },
      "order": {
        "customerOrderNumber": "N-2026-05-27-TEST-03",
        "orderNumbers": {
          "platformOrderNumber": "platform-order-number",
          "referenceNumbers": [
            "ref-number-1",
            "ref-number-2"
          ]
        }
      },
      "shipment": {
        "shipTo": {
          "contact": {
            "firstName": "Alex",
            "lastName": "Smith",
            "phone": "8554377467",
            "email": "[email protected]"
          },
          "address": {
            "streetLines": [
              "18 Distribution Blvd"
            ],
            "city": "Edison",
            "state": "New jersey",
            "postalCode": "08817",
            "countryCode": "US"
          }
        },
        "shipFrom": {
          "contact": {
            "firstName": "John",
            "lastName": "Doe",
            "phone": "886900676877",
            "email": "[email protected]"
          },
          "address": {
            "streetLines": [
              "Habucho"
            ],
            "city": "Kishiwada-Shi",
            "state": "Osaka",
            "postalCode": "596-0825",
            "countryCode": "JP"
          }
        },
        "parcels": [
          {
            "weight": 0.5,
            "dimension": {
              "length": 30,
              "width": 20,
              "height": 10
            },
            "items": [
              {
                "descriptionEn": "Muji Ink pen",
                "descriptionLocal": "文具",
                "quantity": 1,
                "unitPrice": {
                  "amount": 29.99,
                  "currency": "USD"
                },
                "unitWeight": 0.5
              }
            ]
          }
        ]
      },
      "serviceOptions": [
        {
          "code": "V1",
          "value": "云途预缴"
        }
      ],
      "courierOptions": {
        "yunexpress": {
          "sourceCode": "YT",
          "sensitiveType": "D"
        }
      }
  }'

const response = await fetch('https://sandbox.flexforward.com/labels', {
  method: 'POST',
  headers: {
    'x-rr-apikey': 'YOUR_API_KEY',
    'x-rr-apitoken': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    {
          idempotencyKey: 'unique-key-per-request',
          courier: 'yunexpress',
          service: {
            productCode: 'HKMUZXR'
          },
          label: {
            format: 'PDF'
          },
          units: {
            weight: 'KG',
            dimension: 'CM'
          },
          order: {
            customerOrderNumber: 'N-2026-05-27-TEST-03',
            orderNumbers: {
              platformOrderNumber: 'platform-order-number',
              referenceNumbers: [
                'ref-number-1',
                'ref-number-2'
              ]
            }
          },
          shipment: {
            shipTo: {
              contact: {
                firstName: 'Alex',
                lastName: 'Smith',
                phone: '8554377467',
                email: '[email protected]'
              },
              address: {
                streetLines: [
                  '18 Distribution Blvd'
                ],
                city: 'Edison',
                state: 'New jersey',
                postalCode: '08817',
                countryCode: 'US'
              }
            },
            shipFrom: {
              contact: {
                firstName: 'John',
                lastName: 'Doe',
                phone: '886900676877',
                email: '[email protected]'
              },
              address: {
                streetLines: [
                  'Habucho'
                ],
                city: 'Kishiwada-Shi',
                state: 'Osaka',
                postalCode: '596-0825',
                countryCode: 'JP'
              }
            },
            parcels: [
              {
                weight: 0.5,
                dimension: {
                  length: 30,
                  width: 20,
                  height: 10
                },
                items: [
                  {
                    descriptionEn: 'Muji Ink pen',
                    descriptionLocal: '文具',
                    quantity: 1,
                    unitPrice: {
                      amount: 29.99,
                      currency: 'USD'
                    },
                    unitWeight: 0.5
                  }
                ]
              }
            ]
          },
          serviceOptions: [
            {
              code: 'V1',
              value: '云途预缴'
            }
          ],
          courierOptions: {
            yunexpress: {
              sourceCode: 'YT',
              sensitiveType: 'D'
            }
          }
        }
  })
});
const label = await response.json();
console.log(label.id); // Use this ID for document retrieval and tracking

import requests

response = requests.post(
    'https://sandbox.flexforward.com/labels',
    headers={
        'x-rr-apikey': 'YOUR_API_KEY',
        'x-rr-apitoken': 'YOUR_API_TOKEN',
    },
    json={
        'idempotencyKey': 'unique-key-per-request',
        'courier': 'yunexpress',
        'service': {
            'productCode': 'HKMUZXR'
        },
        'label': {
            'format': 'PDF'
        },
        'units': {
            'weight': 'KG',
            'dimension': 'CM'
        },
        'order': {
            'customerOrderNumber': 'N-2026-05-27-TEST-03',
            'orderNumbers': {
                'platformOrderNumber': 'platform-order-number',
                'referenceNumbers': [
                    'ref-number-1',
                    'ref-number-2'
                ]
            }
        },
        'shipment': {
            'shipTo': {
                'contact': {
                    'firstName': 'Alex',
                    'lastName': 'Smith',
                    'phone': '8554377467',
                    'email': '[email protected]'
                },
                'address': {
                    'streetLines': [
                        '18 Distribution Blvd'
                    ],
                    'city': 'Edison',
                    'state': 'New jersey',
                    'postalCode': '08817',
                    'countryCode': 'US'
                }
            },
            'shipFrom': {
                'contact': {
                    'firstName': 'John',
                    'lastName': 'Doe',
                    'phone': '886900676877',
                    'email': '[email protected]'
                },
                'address': {
                    'streetLines': [
                        'Habucho'
                    ],
                    'city': 'Kishiwada-Shi',
                    'state': 'Osaka',
                    'postalCode': '596-0825',
                    'countryCode': 'JP'
                }
            },
            'parcels': [
                {
                    'weight': 0.5,
                    'dimension': {
                        'length': 30,
                        'width': 20,
                        'height': 10
                    },
                    'items': [
                        {
                            'descriptionEn': 'Muji Ink pen',
                            'descriptionLocal': '文具',
                            'quantity': 1,
                            'unitPrice': {
                                'amount': 29.99,
                                'currency': 'USD'
                            },
                            'unitWeight': 0.5
                        }
                    ]
                }
            ]
        },
        'serviceOptions': [
            {
                'code': 'V1',
                'value': '云途预缴'
            }
        ],
        'courierOptions': {
            'yunexpress': {
                'sourceCode': 'YT',
                'sensitiveType': 'D'
            }
        }
    }
)
label = response.json()
print(label['id'])  # Use this ID for document retrieval and tracking

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

201 Created

{
  "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`。

使用相同的 idempotencyKey 重试请求时，API 会返回 HTTP 200 和原始结果，而不会创建重复标签。详情请参阅幂等性与重试。

步骤 3：获取标签文件

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

curl https://sandbox.flexforward.com/labels/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "url": "https://label-documents.example.com/labels/a1b2c3d4.pdf",
  "labelFormat": "pdf"
}

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

步骤 4：追踪货件

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

curl https://sandbox.flexforward.com/tracking/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

200 OK

{
  "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 字段提供货件的概要状态。完整的追踪状态列表请参阅核心概念。

成功验证

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

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

下一步

错误处理

了解错误响应及如何排查常见问题。

幂等性与重试

学习如何安全地重试请求而不创建重复标签。

核心概念

了解标签生命周期、追踪模型与物流商规范化。

快速开始

指南

使用场景指南

平台

快速入门

快速入门

前提条件

步骤 1：身份验证

步骤 2：创建标签

步骤 3：获取标签文件

步骤 4：追踪货件

成功验证

下一步

错误处理

幂等性与重试

核心概念

​快速入门

​前提条件

​步骤 1：身份验证

​步骤 2：创建标签

​步骤 3：获取标签文件

​步骤 4：追踪货件

​成功验证

​下一步

错误处理

幂等性与重试

核心概念

快速入门

前提条件

步骤 1：身份验证

步骤 2：创建标签

步骤 3：获取标签文件

步骤 4：追踪货件

成功验证

下一步