跳轉到主要內容

​
快速入門

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

​
前提條件

  • API 令牌（取得方式請參閱身份驗證）
  • curl 或任何 HTTP 用戶端
  • 開發環境基礎 URL：https://sandbox.flexforward.com
測試請使用開發環境。該環境連接至物流業者的沙盒服務，不會建立實際的配送。

​
步驟 1：身份驗證

在每個請求的 Authorization 標頭中包含您的 Bearer 令牌： 
Authorization: Bearer YOUR_API_TOKEN
令牌最佳實踐與錯誤回應請參閱身份驗證頁面。

​
步驟 2：建立標籤

發送包含配送資訊的 POST /labels 請求。idempotencyKey 確保重試相同的請求不會建立重複標籤。
最低限必填欄位： 需要 idempotencyKey、courier、service.shipperAccountId、service.productCode、shipment.shipTo（包含 firstName 的 contact 以及包含 countryCode、city、postalCode、streetLines 的 address），以及包含 weight 和至少一個 item（descriptionEn、quantity、unitPrice、unitWeight）的 parcel。shipment.shipFrom 欄位在特定物流業者和配送路線中為必填 — 請在上線期間向 Flex Forward 團隊確認您的需求。
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": {
      "shipperAccountId": "your-account-id",
      "productCode": "YEXP01"
    },
    "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
            }
          ]
        }
      ]
    }
  }'
請求成功時，回傳 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 "Authorization: Bearer YOUR_API_TOKEN"
200 OK
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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 "Authorization: Bearer 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 欄位提供貨件的概要狀態。完整的追蹤狀態列表請參閱核心概念。

​
成功驗證

完成此快速入門後，請驗證您可以：
  • 使用 Bearer 令牌成功驗證身份
  • 在開發環境建立測試標籤
  • 取得可列印的標籤文件（PDF 或 PNG）
  • 取得測試標籤的正規化追蹤更新

​
下一步

錯誤處理

了解錯誤回應及如何排解常見問題。

冪等性與重試

學習如何安全地重試請求而不建立重複標籤。

核心概念

了解標籤生命週期、追蹤模型與物流業者正規化。