xPdf Label API - JSON 数据结构完整参考

端点: POST /api/v1/label | /api/v2/label | /api/v3/label
Content-Type: application/json
响应: application/pdf (二进制流)

三个接口的 请求体格式完全一致，均接收 LabelRequest 数组或单个对象。

---

请求格式

// 数组格式 (批量)
[ { "pdf_params": {...}, "items": [...] }, ... ]

// 或单对象格式
{ "pdf_params": {...}, "items": [...] }

---

LabelRequest (根对象)

字段	类型	必填	默认值	说明
tracking_number	string	❌	-	请求追踪编号，用于日志和调试
pdf_params	PdfParams	❌	见下	PDF 文档全局配置
items	Item[]	⚠️	-	页面内容数组，每个 Item 生成一页 (实际必填)

---

PdfParams (PDF 全局配置)

页面尺寸

字段	类型	必填	默认值	单位	说明
width	number	❌	100	mm	页面宽度
height	number	❌	150	mm	页面高度

文件输出

字段	类型	必填	默认值	说明
save_file	boolean	❌	false	是否在服务端保存 PDF 文件
output_dir	string	❌	"pdf_files"	服务端保存目录路径
file_name	string	❌	"{timestamp}.pdf"	文件名模板，支持 {timestamp}、{tracking_number} 变量
global_font	string	❌	系统默认	全局默认字体名称
rust_log	string	❌	"close"	日志级别: debug / info / warn / error / close

PDF 元数据 (Metadata)

字段	类型	必填	说明
metadata_title	string	⚠️	文档标题 (PDF/UA-1 必填，否则触发 E003)
metadata_authors	string	❌	作者姓名
metadata_subject	string	❌	主题/关键词
metadata_creator	string	❌	创建软件名称
metadata_producer	string	❌	生成器名称
metadata_creation_date	string	❌	创建日期 (ISO 8601 格式)
metadata_modification_date	string	❌	修改日期 (ISO 8601 格式)
metadata_language	string	❌	ISO 639-1 语言代码 (如 "zh", "en")，自动检测

PDF/A 合规配置

字段	类型	必填	默认值	说明
pdf_profile	string	❌	""	PDF 合规等级

支持的 pdf_profile 值:

值	标准	说明
"" (空字符串)	标准 PDF	无合规要求，体积最小
"pdfa-1b"	PDF/A-1b	基础归档
"pdfa-2b"	PDF/A-2b	支持透明度
"pdfa-3b"	PDF/A-3b	可嵌入附件
"pdfa-4"	PDF/A-4	最新标准
"pdfa-1a"	PDF/A-1a	高级归档 + 无障碍
"pdfa-2a"	PDF/A-2a	高级归档 + 无障碍
"pdfa-3a"	PDF/A-3a	高级归档 + 无障碍
"pdfa-ua1"	PDF/UA-1	通用无障碍标准 (需 metadata_title)

⚠️ 填写不支持的值会触发 E002 错误层叠加。

---

Item (内容容器)

每个 Item 代表一个 PDF 页面上的元素分组。

字段	类型	必填	说明
tracking_number	string	❌	元素级追踪编号
1d_params	OneDParams[]	❌	一维条码数组
2d_params	TwoDParams[]	❌	二维码数组
text_elements	TextElement[]	❌	文本元素数组
lines	Line[]	❌	线条数组
images	ImageElement[]	❌	图片数组
rectangles	Rectangle[]	❌	矩形数组

---

OneDParams (一维条码)

此对象数组在 Item 中的 JSON Key 为 1d_params

字段	类型	必填	单位	说明
1d_content	string	✅	-	编码内容 (条码数据)
format	string	✅	-	码制类型 (见下表)
position	Position	✅	-	位置坐标对象 {x, y}
size	BarcodeSize	✅	-	尺寸对象 {height, module_width?, width?}
orientation	integer	❌	°	旋转角度: 0 / 90 / 180 / 270
color	string	❌	-	条码颜色 (Hex: "#000000")
background_color	string	❌	-	背景颜色 (Hex)
line	number	❌	mm	条线宽度
quiet_zone	integer	❌	模块	静区大小 (条码周围空白)
gs1_format	boolean	❌	-	是否使用 GS1 格式编码
bearer_bar_shape	string	❌	-	承载条形状: "frame" / "top_bottom"
bearer_bar_thickness	number	❌	mm	承载条厚度
human_readable_text	HumanReadableText	❌	-	条码附属文本配置

支持的 format 值: Code128, Code39, Code93, EAN13, EAN8, UPCA, UPCE, ITF, Codabar

---

TwoDParams (二维码)

此对象数组在 Item 中的 JSON Key 为 2d_params

字段	类型	必填	单位	说明
2d_content	string	✅	-	编码内容
content	string	❌	-	2d_content 的别名
format	string	✅	-	码制类型 (见下表)
module_size	number	❌	mm	单模块尺寸 (一个"像素"的大小)
x	number	✅	mm	X 坐标 (左上角原点)
y	number	✅	mm	Y 坐标 (左上角原点)
color	string	❌	-	前景色 (Hex: "#000000")
background_color	string	❌	-	背景色 (Hex)
quiet_zone	integer	❌	模块	静区大小
orientation	integer	❌	°	旋转角度: 0 / 90 / 180 / 270
shape	string	❌	-	模块形状: "square" / "circle"

支持的 format 值: QRCode, DataMatrix, PDF417, Aztec, MaxiCode

---

Position (位置)

字段	类型	必填	单位	说明
x	number	✅	mm	X 坐标 (左上角原点，向右为正)
y	number	✅	mm	Y 坐标 (左上角原点，向下为正)

---

BarcodeSize (条码尺寸)

字段	类型	必填	单位	说明
height	number	✅	mm	条码高度
module_width	number	❌	mm	单模块宽度 (最细条的宽度)，优先级高于 width
width	number	❌	mm	条码整体宽度

---

HumanReadableText (条码附属文本)

字段	类型	必填	单位	说明
enabled	boolean	❌	-	是否显示附属文本，默认 true
content	string	❌	-	显示内容 (覆盖条码数据本身)
font_size	number	❌	pt	字号
font_name	string	❌	-	字体名称 (需预加载)
color	string	❌	-	文字颜色 (Hex)
bold	boolean	❌	-	是否粗体
align	string	❌	-	对齐方式: "Left" / "Center" / "Right"
offset_y	number	❌	mm	Y 轴偏移量 (正值向下)
side	integer	❌	-	显示位置: 0 = 下方, 1 = 上方

---

TextElement (独立文本)

字段	类型	必填	单位	说明
x	number	✅	mm	X 坐标
y	number	✅	mm	Y 坐标
content	string	✅	-	文本内容，支持 \n 换行和 [B]...[/B] 加粗
label	string	❌	-	标签标识 (仅用于调试，不显示在 PDF)
font_size	number	❌	pt	字号，默认 12
font_name	string	❌	-	字体名称 (需预加载)
color	string	❌	-	文字颜色 (Hex: "#000000")
bold	boolean	❌	-	是否粗体
line_spacing	number	❌	pt	行间距
width	number	❌	mm	文本框宽度 (启用自动换行)
height	number	❌	mm	文本框高度
overflow	string	❌	-	溢出处理: "none" / "clip" / "ellipsis"
v_align	string	❌	-	垂直对齐: "Top" / "Middle" / "Bottom"
direction	integer	❌	-	文字方向: 0 = 水平

---

Line (线条)

字段	类型	必填	单位	说明
x1	number	✅	mm	起点 X 坐标
y1	number	✅	mm	起点 Y 坐标
x2	number	✅	mm	终点 X 坐标
y2	number	✅	mm	终点 Y 坐标
thickness	number	❌	mm	线条粗细，默认 1
color	string	❌	-	线条颜色 (Hex)

---

ImageElement (图片)

字段	类型	必填	单位	说明
x	number	✅	mm	X 坐标
y	number	✅	mm	Y 坐标
width	number	✅	mm	显示宽度
height	number	✅	mm	显示高度
base64	string	❌	-	Base64 编码图片数据 (优先级 1)
image_path	string	❌	-	服务端图片路径 (优先级 2)
image_name	string	❌	-	预加载图片名称 (优先级 3)

💡 三种图片来源优先级: base64 > image_path > image_name

---

Rectangle (矩形)

字段	类型	必填	单位	说明
x	number	✅	mm	左上角 X 坐标
y	number	✅	mm	左上角 Y 坐标
width	number	✅	mm	宽度
height	number	✅	mm	高度
thickness	number	❌	mm	边框粗细
color	string	❌	-	边框/填充颜色 (Hex)
fill	boolean	❌	-	是否填充 (true) 或仅描边 (false)
radius	number	❌	mm	圆角半径

---

坐标系统

• 原点: 页面左上角 (0, 0)
• X 轴: 水平向右为正
• Y 轴: 垂直向下为正
• 单位: 所有坐标和尺寸均为 毫米 (mm)

---

错误码

错误码	触发条件	表现
E001	文本包含当前字体无法渲染的字符 (缺失字形)	PDF 上覆盖红色 "E001" 层
E002	pdf_profile 为不支持的非空值	PDF 上覆盖红色 "E002" 层
E003	pdfa-ua1 模式下缺失 metadata_title	PDF 上覆盖 "E003" 层

---

完整示例

[
  {
    "pdf_params": {
      "width": 100,
      "height": 60,
      "pdf_profile": "pdfa-2b",
      "metadata_title": "Shipping Label",
      "metadata_language": "en"
    },
    "items": [
      {
        "1d_params": [
          {
            "1d_content": "1234567890",
            "format": "Code128",
            "position": { "x": 5, "y": 5 },
            "size": { "height": 15, "module_width": 0.3 },
            "human_readable_text": {
              "enabled": true,
              "font_size": 8,
              "align": "Center"
            }
          }
        ],
        "2d_params": [
          {
            "2d_content": "https://example.com",
            "format": "QRCode",
            "x": 70,
            "y": 5,
            "module_size": 1.2
          }
        ],
        "text_elements": [
          {
            "x": 5,
            "y": 45,
            "content": "Ship To: John Doe",
            "font_size": 10,
            "bold": true
          }
        ]
      }
    ]
  }
]

---

📌 文档版本: 2026-01-04
📌 源文件: models.rs, api.rs