> ## 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-Hant/authentication)） * `curl` 或任何 HTTP 用戶端 * 開發環境基礎 URL：`https://sandbox.flexforward.com` 測試請使用開發環境。該環境連接至物流業者的沙盒服務，不會建立實際的配送。 ## 步驟 1：身份驗證 在每個請求的 `Authorization` 標頭中包含您的 Bearer 令牌： ``` Authorization: Bearer YOUR_API_TOKEN ``` 令牌最佳實踐與錯誤回應請參閱[身份驗證](/zh-Hant/authentication)頁面。 ## 步驟 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 團隊確認您的需求。 ```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 ``` 請求成功時，回傳 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`。 | 使用相同的 `idempotencyKey` 重試請求時，API 會回傳 HTTP 200 和原始結果，而不會建立重複標籤。詳情請參閱[冪等性與重試](/zh-Hant/idempotency-and-retries)。 ## 步驟 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-Hant/core-concepts#追蹤狀態模型)。 ## 成功驗證 完成此快速入門後，請驗證您可以： * [ ] 使用 Bearer 令牌成功驗證身份 * [ ] 在開發環境建立測試標籤 * [ ] 取得可列印的標籤文件（PDF 或 PNG） * [ ] 取得測試標籤的正規化追蹤更新 ## 下一步 了解錯誤回應及如何排解常見問題。 學習如何安全地重試請求而不建立重複標籤。 了解標籤生命週期、追蹤模型與物流業者正規化。