> ## 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-Hans/guides/tracking-updates">
    打印并贴附标签后，监控发货进度。
  </Card>

  <Card title="错误处理" icon="triangle-exclamation" href="/zh-Hans/error-handling">
    所有 HTTP 状态码和错误响应格式的完整参考。
  </Card>
</CardGroup>