此頁面由英文翻譯而成。英文版為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。

取得標籤文件

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

取得文件 URL

使用標籤建立回應中的 id。{id} 可接受標籤 UUID，或建立標籤時提供的 customerOrderNumber：

curl https://api.flexforwardship.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

const response = await fetch(
  'https://api.flexforwardship.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479',
  { headers: { 'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN' } }
);
const labelDoc = await response.json();
console.log(labelDoc.url); // URL to download the document

import requests

response = requests.get(
    'https://api.flexforwardship.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479',
    headers={'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN'}
)
label_doc = response.json()
print(label_doc['url'])  # URL to download the document

回應

200 OK

{
  "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 下載文件：

curl -o label.pdf "https://label-cdn.yunexpress.cn/labels/YT2503010001.pdf"

import { writeFile } from 'fs/promises';

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

doc_response = requests.get(label_doc['url'])
with open(f"label.{label_doc['labelFormat']}", 'wb') as f:
    f.write(doc_response.content)

文件行為

時限性 URL — url 為短期下載連結（目前約 1 小時有效，未來可能調整）。請勿保存此連結。需要下載時，請重新呼叫 GET /labels/{id} 以取得新的 URL。
格式 — 建立標籤時將 label.format 設為 "PDF" 或 "PNG"，省略時使用 PDF。GET /labels/{id} 會以小寫 labelFormat: "pdf" 或 "png" 回傳所選格式；此呼叫不會變更格式。本頁範例取得 PDF 標籤。
重新取得 — 每次呼叫都會為同一份文件回傳新的 URL。文件內容不變，但 URL 字串會改變。

批次取得

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

路徑參數會以逗號分割。每個片段會去除前後空白，空片段會被丟棄，重複的會合併，因此 a,,a, b 會被視為 a,b。
只剩一個識別碼時，回傳單一標籤的回應（不存在則為 404，物流業者提交失敗的標籤則為 422）。兩個以上則回傳下方說明的 labels 陣列格式。
不存在的標籤與物流業者提交失敗的標籤會從 labels 中省略，不會有錯誤項目。若所有識別碼都無法解析，請求回傳 404。
目前沒有強制的上限。請將批次保持在較小規模（數十個而非數百個）；每個識別碼都需要向物流業者解析一份文件。

新的標籤請求會拒絕 customerOrderNumber 中包含逗號；目前的限制請參閱客戶訂單編號。若舊版記錄的訂單編號中含有逗號，由於此端點會以逗號分割識別碼，請改用標籤 UUID 取得該記錄。

curl "https://api.flexforwardship.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02" \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

const response = await fetch(
  'https://api.flexforwardship.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02',
  { headers: { 'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN' } }
);
const result = await response.json();
result.labels.forEach(label => console.log(label.url));

import requests

response = requests.get(
    'https://api.flexforwardship.com/labels/f47ac10b-58cc-4372-a567-0e02b2c3d479,N2026-05-13-TEST-02',
    headers={'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN'}
)
result = response.json()
for label in result['labels']:
    print(label['url'])

批次回應

200 OK

{
  "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`	成功解析的標籤文件陣列。找不到或失敗的標籤會被省略；請將回傳的 `id` / `customerOrderNumber` 與您的請求比對以偵測缺漏。
`labels[].id`	標籤的 UUID。
`labels[].customerOrderNumber`	與此標籤關聯的客戶訂單編號。
`labels[].url`	航空提單文件的直接下載 URL。
`labels[].labelFormat`	該標籤的文件格式：`pdf` 或 `png`。

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

錯誤處理

狀態碼	意義	處理方式
200	已取得文件 URL	從 `url` 欄位下載
403	帳戶存取被拒	您的帳戶不被允許呼叫 API（例如遭封鎖的帳戶）
404	找不到標籤	您帳戶中不存在該 UUID 或 `customerOrderNumber` 對應的標籤。其他帳戶擁有的標籤同樣會回報 404。
422	標籤建立失敗	單一請求的標籤在物流業者端失敗；修正原因後建立替代標籤。失敗的標籤會從批次結果中省略。
502	上游服務錯誤	使用指數退避重試

快速開始

指南

使用場景指南

平台

取得標籤文件

取得標籤文件

取得文件 URL

回應

下載並列印

文件行為

批次取得

批次回應

錯誤處理

後續步驟

追蹤出貨

錯誤處理

​取得標籤文件

​取得文件 URL

​回應

​下載並列印

​文件行為

​批次取得

​批次回應

​錯誤處理

​後續步驟

追蹤出貨

錯誤處理

取得標籤文件

取得文件 URL

回應

下載並列印

文件行為

批次取得

批次回應

錯誤處理

後續步驟