接口名称
打印面单 V2 (Print Label V2)
接口地址
/api/shipper/v1/pclLabel/printLabelV2
请求方式
POST
接口描述
该接口用于打印或下载物流面单（标签）。根据请求参数不同，支持以下模式：
- 打印模式（PDF）：返回 PDF 文件流，前端创建隐藏 iframe 并调用浏览器打印功能
- 打印模式（ZPL）：返回 ZPL 格式文件流，用于热敏打印机
- 下载模式：返回 PDF 文件流，前端触发浏览器下载
请求头
参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
sessionId | String | 是 | 登录会话ID |
language | String | 是 | 语言 |
Content-Type | String | 是 | application/json;charset=UTF-8 |
Accept | String | 是 | application/json, text/plain, / |
语言取值：
值 | 说明 |
|---|---|
zh_CN | 中文 |
en_US | 英文 |
请求参数
参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
uuids | String | 是 | 订单UUID列表，多个UUID用逗号分隔 |
pageSize | Number | 是 | 纸张尺寸编码，详见下表 |
packlist | Number | 是 | 是否包含装箱单，0=不包含，1=包含 |
labelFormat | String | 否 | 标签格式，不传或传-1为PDF打印模式 |
pageSize 纸张尺寸编码：
值 | 说明 |
|---|---|
1 | 10*15 热敏纸 |
2 | A4 纸 |
4 | 10*10 热敏纸 |
空字符串 | 仅装箱单（无面单） |
labelFormat 标签格式：
值 | 说明 |
|---|---|
不传 / -1 | PDF 格式（默认） |
ZPL | ZPL 格式（用于热敏打印机，dpi300） |
packlist 装箱单选项：
值 | 说明 |
|---|---|
0 或 空字符串 | 不包含装箱单 |
1 | 包含装箱单 |
请求示例
curl 'https://tracking-qa.etowertech.com/api/shipper/v1/pclLabel/printLabelV2' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'language: zh_CN' \
-H 'sessionId: vP1l43F_OqvoTUWBcaAtyg' \
--data-raw '{"uuids":"wAy1xp0eL5dtQ1W7c9GpUw","pageSize":1,"packlist":1}'
返回说明
响应类型：
- PDF 格式：application/pdf;charset=UTF-8
- ZPL 格式：application/octet-stream
响应头：
参数 | 说明 |
|---|---|
Content-Disposition | 文件名，如：attachment;filename=label.pdf |
Content-Type | 文件类型 |
Cache-Control | no-cache |
返回说明：
- 返回的是文件流（PDF 或 ZPL 格式）
- 前端根据 labelFormat 参数决定是打印还是下载：
- 当 labelFormat 不传或为 -1 时：前端创建隐藏 iframe，加载 PDF 后调用 window.print() 打印
- 当 labelFormat 为 ZPL 时：前端下载 ZPL 文件
- 其他情况：前端触发文件下载
错误响应
当请求失败时，返回 JSON 格式错误信息：
错误码 | 说明 |
|---|---|
0 | 成功 |
0014 | 会话超时，需要重新登录 |
0017 | 认证失败 |
200001 | 权限不足 |
前端打印选项配置
前端提供的打印面单下拉选项配置：
PRINT_LABEL_OPTIONS: [
{ label: '10*15', pageSize: 1, packlist: '' },
{ label: '10*15(装箱单)', pageSize: 1, packlist: 1 },
{ label: '10*10', pageSize: 4, packlist: '' },
{ label: '10*10(装箱单)', pageSize: 4, packlist: 1 },
{ label: 'A4', pageSize: 2, packlist: '' },
{ label: 'A4(装箱单)', pageSize: 2, packlist: 1 },
{ label: '装箱单', pageSize: '', packlist: 1 },
{ label: '10*15 ZPL（dpi300）', pageSize: 1, packlist: '', labelFormat: 'ZPL' },
{ label: '10*10 ZPL（dpi300）', pageSize: 4, packlist: '', labelFormat: 'ZPL' }
]
选项说明：
显示标签 | pageSize | packlist | labelFormat | 模式 |
|---|---|---|---|---|
10*15 | 1 | '' | PDF 打印 | |
10*15(装箱单) | 1 | 1 | PDF 打印 | |
10*10 | 4 | '' | PDF 打印 | |
10*10(装箱单) | 4 | 1 | PDF 打印 | |
A4 | 2 | '' | PDF 打印 | |
A4(装箱单) | 2 | 1 | PDF 打印 | |
装箱单 | '' | 1 | PDF 打印 | |
10*15 ZPL（dpi300） | 1 | '' | ZPL | ZPL 下载 |
10*10 ZPL（dpi300） | 4 | '' | ZPL | ZPL 下载 |