此页面由英文翻译而成。英文版为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。

获取标签文档

创建配送标签后，使用 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

响应

下载并打印

文档行为

批量获取

批量响应

错误处理

后续步骤