> ## 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が返されます。このエンドポイントは本質的にべき等です。

## バッチ取得

カンマ区切りの識別子を渡すことで、1回のリクエストで複数のラベルドキュメントを取得できます。ラベル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="/ja/guides/tracking-updates">
    ラベルを印刷して荷物に貼付した後、出荷状況を監視します。
  </Card>

  <Card title="エラーハンドリング" icon="triangle-exclamation" href="/ja/error-handling">
    すべてのHTTPステータスコードとエラーレスポンス形式の完全なリファレンス。
  </Card>
</CardGroup>