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

# 取得標籤文件

> 如何在建立標籤後取得並使用可列印的航空提單文件

<Note>
  此頁面由英文翻譯而成。[英文版](/introduction)為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。
</Note>

# 取得標籤文件

建立配送標籤後，使用 `GET /labels/{id}` 取得可列印的航空提單文件。傳入單一識別碼或以逗號分隔的多個識別碼即可進行批次取得。本指南涵蓋取得流程、批次請求、文件格式及實務注意事項。

## 取得文件 URL

使用標籤建立回應中的 `id`：

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479',
    { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }
  );
  const labelDoc = await response.json();
  console.log(labelDoc.url); // URL to download the document
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
  )
  label_doc = response.json()
  print(label_doc['url'])  # URL to download the document
  ```
</CodeGroup>

### 回應

```json 200 OK theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customerOrderNumber": "N2026-05-13-TEST-01",
  "url": "https://label-cdn.yunexpress.cn/labels/YT2503010001.pdf",
  "labelFormat": "pdf"
}
```

| 欄位                    | 說明                  |
| --------------------- | ------------------- |
| `id`                  | 標籤的 UUID（與請求參數相同）。  |
| `customerOrderNumber` | 與此標籤關聯的客戶訂單編號。      |
| `url`                 | 航空提單文件的直接下載 URL。    |
| `labelFormat`         | 文件格式：`pdf` 或 `png`。 |

## 下載並列印

從回傳的 `url` 下載文件：

<CodeGroup>
  ```bash cURL theme={null}
  curl -o label.pdf "https://label-cdn.yunexpress.cn/labels/YT2503010001.pdf"
  ```

  ```javascript Node.js theme={null}
  import { writeFile } from 'fs/promises';

  const docResponse = await fetch(labelDoc.url);
  const buffer = Buffer.from(await docResponse.arrayBuffer());
  await writeFile(`label.${labelDoc.labelFormat}`, buffer);
  ```

  ```python Python theme={null}
  doc_response = requests.get(label_doc['url'])
  with open(f"label.{label_doc['labelFormat']}", 'wb') as f:
      f.write(doc_response.content)
  ```
</CodeGroup>

## 文件行為

* **永久 URL** — 文件 URL 不會過期。您可以儲存 URL 並隨時下載文件。
* **格式** — 文件以 PDF 或 PNG 提供，取決於物流業者和標籤設定。
* **重新取得** — 多次呼叫 `GET /labels/{id}` 會回傳相同的 URL。此端點本質上具有冪等性。

## 批次取得

透過傳入以逗號分隔的識別碼，即可在單一請求中取得多個標籤文件。您可以混合使用標籤 UUID 和客戶訂單編號。

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02" \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02',
    { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }
  );
  const result = await response.json();
  result.labels.forEach(label => console.log(label.url));
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.flexforward.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
  )
  result = response.json()
  for label in result['labels']:
      print(label['url'])
  ```
</CodeGroup>

### 批次回應

```json 200 OK theme={null}
{
  "labels": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "customerOrderNumber": "N2026-05-13-TEST-01",
      "url": "https://label-cdn.yunexpress.cn/labels/YT2503010001.pdf",
      "labelFormat": "pdf"
    },
    {
      "id": "c8d9e0f1-2345-6789-abcd-ef0123456789",
      "customerOrderNumber": "N2026-05-13-TEST-02",
      "url": "https://label-cdn.yunexpress.cn/labels/YT2503010002.pdf",
      "labelFormat": "pdf"
    }
  ]
}
```

| 欄位                             | 說明                         |
| ------------------------------ | -------------------------- |
| `labels`                       | 成功解析的標籤文件陣列。找不到或失敗的標籤會被省略。 |
| `labels[].id`                  | 標籤的 UUID。                  |
| `labels[].customerOrderNumber` | 與此標籤關聯的客戶訂單編號。             |
| `labels[].url`                 | 航空提單文件的直接下載 URL。           |
| `labels[].labelFormat`         | 文件格式：`pdf` 或 `png`。        |

<Note>
  找不到或失敗的標籤會從回應中被靜默省略。請將回傳的 `labels` 陣列與您請求的識別碼進行比對，以偵測未成功解析的項目。
</Note>

## 錯誤處理

| 狀態碼 | 意義        | 處理方式          |
| --- | --------- | ------------- |
| 200 | 已取得文件 URL | 從 `url` 欄位下載  |
| 403 | 存取被拒      | 該標籤屬於其他帳戶     |
| 404 | 找不到標籤     | 請確認標籤 ID 是否正確 |
| 502 | 上游服務錯誤    | 使用指數退避重試      |

## 後續步驟

<CardGroup cols={2}>
  <Card title="追蹤出貨" icon="location-dot" href="/zh-Hant/guides/tracking-updates">
    列印並貼附標籤後，監控出貨進度。
  </Card>

  <Card title="錯誤處理" icon="triangle-exclamation" href="/zh-Hant/error-handling">
    所有 HTTP 狀態碼和錯誤回應格式的完整參考。
  </Card>
</CardGroup>