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

# Flex Forward API

Flex Forward 提供單一 API 來建立配送標籤、取得提單文件，以及追蹤貨件。透過統一的請求格式、正規化的追蹤資料與內建冪等性，一次整合即可對接多個物流業者。

## 核心工作流程

<CardGroup cols={3}>
  <Card title="建立標籤" icon="tag" href="/zh-hant/api-reference/labels/create-label">
    透過支援的物流業者建立配送標籤，支援冪等請求。
  </Card>

  <Card title="取得標籤文件" icon="file-pdf" href="/zh-hant/api-reference/labels/get-label">
    取得已建立標籤的提單 PDF 或 PNG。
  </Card>

  <Card title="貨件追蹤" icon="location-dot" href="/zh-hant/api-reference/tracking/get-tracking">
    以統一格式取得所有物流業者的即時追蹤資訊。
  </Card>
</CardGroup>

## 三步驟開始

<Steps>
  <Step title="取得 API 存取權限">
    聯繫 Flex Forward 團隊 [flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com) 申請 API 認證資訊。您將收到用於身份驗證的 Bearer 令牌。
  </Step>

  <Step title="建立您的第一個標籤">
    發送包含配送資訊的 `POST /labels` 請求。API 將回傳標籤 ID 和追蹤號碼。
  </Step>

  <Step title="取得文件並追蹤">
    使用標籤 ID 取得提單文件（`GET /labels/{id}`）並追蹤貨件（`GET /tracking/{id}`）。
  </Step>
</Steps>

<Card title="按照快速入門指南操作" icon="rocket" href="/zh-Hant/quickstart">
  從身份驗證到建立第一個標籤的逐步指南。
</Card>

## 整合流程

```mermaid theme={null}
graph LR
    A["身份驗證<br/>(Bearer 令牌)"] --> B["建立標籤<br/>POST /labels"]
    B --> C["取得文件<br/>GET /labels/{id}"]
    B --> D["追蹤貨件<br/>GET /tracking/{id}"]
    D -->|"輪詢更新"| D
```

## 第一個請求範例

```bash theme={null}
curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ord-20250301-abc123",
    "courier": "yunexpress",
    "service": {
      "productCode": "HKMUZXR"
    },
    "shipment": {
      "shipFrom": {
        "contact": { "firstName": "Sender", "lastName": "Name", "phone": "+81-90-1234-5678" },
        "address": { "countryCode": "JP", "city": "Tokyo", "postalCode": "100-0001", "streetLines": ["1-1 Marunouchi"] }
      },
      "shipTo": {
        "contact": { "firstName": "Recipient", "lastName": "Name", "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
        }]
      }]
    }
  }'
```

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

## 正式環境支援範圍

Flex Forward 目前支援透過 YunExpress 進行正式環境的配送，涵蓋全球跨境電商物流。

| 物流業者       | 代碼           | 服務區域   |
| ---------- | ------------ | ------ |
| YunExpress | `yunexpress` | 全球跨境電商 |

可根據物流路線需求及帳戶建置來啟用額外的物流業者。如需了解物流業者的可用性，請聯繫 Flex Forward 團隊。

## 環境

| 環境 | 基礎 URL                            |
| -- | --------------------------------- |
| 正式 | `https://api.flexforward.com`     |
| 開發 | `https://sandbox.flexforward.com` |

所有 API 請求必須透過 HTTPS 發送。開發環境連接至物流業者的沙盒服務，可安全進行測試。

<Card title="環境詳情" icon="server" href="/zh-Hant/environments">
  認證資訊分離、環境行為與營運注意事項。
</Card>

## 平台可靠性

<CardGroup cols={2}>
  <Card title="身份驗證" icon="key" href="/zh-Hant/authentication">
    Bearer 令牌驗證與認證資訊管理最佳實踐。
  </Card>

  <Card title="錯誤處理" icon="triangle-exclamation" href="/zh-Hant/error-handling">
    HTTP 狀態碼、錯誤回應格式與疑難排解指南。
  </Card>

  <Card title="冪等性與重試" icon="rotate" href="/zh-Hant/idempotency-and-retries">
    防止重複建立標籤並安全地重試請求。
  </Card>

  <Card title="版本管理" icon="code-branch" href="/zh-Hant/versioning">
    API 如何處理變更與向後相容性。
  </Card>
</CardGroup>

## OpenAPI 規格

<Card title="下載 OpenAPI 規格" icon="file-code" href="/flex-forward.yaml">
  下載 OpenAPI 3.1 規格以用於程式碼生成、客戶端 SDK 和 API 工具。
</Card>

## 支援

如需建置協助、整合支援或物流業者可用性諮詢，請聯繫 Flex Forward 團隊：[flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com)

<Card title="支援與常見問題" icon="circle-question" href="/zh-Hant/support">
  技術支援、建置指南與常見問題。
</Card>