此頁面由英文翻譯而成。英文版為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。

快速入門

本指南將引導您完成建立第一個配送標籤、取得標籤文件以及追蹤貨件的流程。

前提條件

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：追蹤貨件

成功驗證

下一步