xPdf API 完整接口文档

版本: v3
端点: POST /api/v3/label
Content-Type: application/json
认证: Authorization: Bearer <token>

📋 概述

xPdf API 接受一个 JSON 数组，每个元素是一个 LabelRequest 对象，返回生成的 PDF 文件（二进制流）。

json

[
  { "pdf_params": {...}, "items": [...] },
  { "pdf_params": {...}, "items": [...] }
]

🏗️ 数据结构总览

LabelRequest
├── tracking_number
├── pdf_params (PdfParams)
│   ├── 页面设置: width, height
│   ├── 文件设置: save_file, output_dir, file_name, global_font
│   ├── 元数据: metadata_*
│   └── 合规配置: pdf_profile
└── items (Item[])
    ├── 一维条码: 1d_params (OneDParams[])
    ├── 二维码: 2d_params (TwoDParams[])
    ├── 文本: text_elements (TextElement[])
    ├── 线条: lines (Line[])
    ├── 图片: images (ImageElement[])
    └── 矩形: rectangles (Rectangle[])

📦 LabelRequest（根对象）

字段名	JSON 类型	Rust 类型	必填	说明
`tracking_number`	`string`	`Option<String>`	❌	请求追踪编号，用于日志和调试
`pdf_params`	`object`	`Option<PdfParams>`	❌	PDF 文档全局配置
`items`	`array`	`Option<Vec<Item>>`	⚠️	页面内容元素列表（实际使用时必填）

📄 PdfParams（PDF 配置）

页面尺寸

字段名	JSON 类型	Rust 类型	单位	默认值	说明
`width`	`number`	`Option<f32>`	mm	100	页面宽度（毫米）
`height`	`number`	`Option<f32>`	mm	150	页面高度（毫米）

文件输出控制

字段名	JSON 类型	Rust 类型	说明
`save_file`	`boolean`	`Option<bool>`	是否在服务器端保存 PDF 文件
`output_dir`	`string`	`Option<String>`	服务端保存路径
`file_name`	`string`	`Option<String>`	保存的文件名
`global_font`	`string`	`Option<String>`	全局默认字体名称
`rust_log`	`string`	`Option<String>`	日志级别：`debug`, `info`, `warn`, `error`

PDF 元数据 (Metadata)

字段名	JSON 类型	Rust 类型	说明
`metadata_title`	`string`	`Option<String>`	文档标题 ⚠️ UA-1 必填
`metadata_authors`	`string`	`Option<String>`	作者姓名
`metadata_subject`	`string`	`Option<String>`	主题/关键词
`metadata_creator`	`string`	`Option<String>`	创建软件名称
`metadata_producer`	`string`	`Option<String>`	生成器名称
`metadata_creation_date`	`string`	`Option<String>`	创建日期 (ISO 8601)
`metadata_modification_date`	`string`	`Option<String>`	修改日期 (ISO 8601)
`metadata_language`	`string`	`Option<String>`	ISO 639-1 语言代码，如 `"zh"`, `"en"`

💡 智能语言检测: 如未提供 metadata_language，系统会自动检测内容语言（支持 CJK/阿拉伯语/希伯来语等），若无法识别则默认为 "und"。

PDF/A 合规配置

字段名	JSON 类型	Rust 类型	说明
`pdf_profile`	`string`	`Option<String>`	PDF/A 合规等级

支持的 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	通用无障碍标准

⚠️ E002 错误: 填写不支持的值（如 "pdfa-4u"）会触发错误层叠加。

📦 Item（内容容器）

每个 Item 代表一组绑定在一起的图形元素。

字段名	JSON 键名	Rust 类型	说明
`tracking_number`	`tracking_number`	`Option<String>`	元素级追踪编号
`two_d_params`	`2d_params`	`Option<Vec<TwoDParams>>`	二维码数组
`one_d_params`	`1d_params`	`Option<Vec<OneDParams>>`	一维条码数组
`text_elements`	`text_elements`	`Option<Vec<TextElement>>`	文本元素数组
`lines`	`lines`	`Option<Vec<Line>>`	线条数组
`images`	`images`	`Option<Vec<ImageElement>>`	图片数组
`rectangles`	`rectangles`	`Option<Vec<Rectangle>>`	矩形数组

📊 OneDParams（一维条码）

字段名	JSON 键名	Rust 类型	单位	说明
`one_d_content`	`1d_content`	`Option<String>`	-	编码内容
`format`	`format`	`Option<String>`	-	码制类型
`position`	`position`	`Option<Position>`	-	位置对象 `{x, y}`
`size`	`size`	`Option<BarcodeSize>`	-	尺寸对象
`orientation`	`orientation`	`Option<i32>`	度	旋转角度 (0/90/180/270)
`color`	`color`	`Option<String>`	-	条码颜色 Hex，如 `"#000000"`
`background_color`	`background_color`	`Option<String>`	-	背景颜色 Hex
`human_readable_text`	`human_readable_text`	`Option<HumanReadableText>`	-	人眼可读文本配置
`line`	`line`	`Option<f32>`	mm	条线宽度
`quiet_zone`	`quiet_zone`	`Option<u32>`	模块	静区大小
`gs1_format`	`gs1_format`	`Option<bool>`	-	是否使用 GS1 格式
`bearer_bar_shape`	`bearer_bar_shape`	`Option<String>`	-	承载条形状
`bearer_bar_thickness`	`bearer_bar_thickness`	`Option<f32>`	mm	承载条厚度

支持的码制 (format): Code128, Code39, Code93, EAN13, EAN8, UPCA, UPCE, ITF, Codabar

📱 TwoDParams（二维码）

字段名	JSON 键名	Rust 类型	单位	说明
`two_d_content`	`2d_content`	`Option<String>`	-	编码内容
`content`	`content`	`Option<String>`	-	编码内容（`2d_content` 别名）
`format`	`format`	`Option<String>`	-	码制类型
`module_size`	`module_size`	`Option<f32>`	mm	单模块尺寸
`x`	`x`	`Option<f32>`	mm	X 坐标
`y`	`y`	`Option<f32>`	mm	Y 坐标
`color`	`color`	`Option<String>`	-	前景色 Hex
`background_color`	`background_color`	`Option<String>`	-	背景色 Hex
`quiet_zone`	`quiet_zone`	`Option<u32>`	模块	静区大小
`orientation`	`orientation`	`Option<i32>`	度	旋转角度
`shape`	`shape`	`Option<String>`	-	模块形状

支持的码制 (format): QRCode, DataMatrix, PDF417, Aztec, MaxiCode

📍 Position（位置）

字段名	JSON 类型	Rust 类型	单位	必填	说明
`x`	`number`	`f32`	mm	✅	X 坐标（左上角原点）
`y`	`number`	`f32`	mm	✅	Y 坐标（左上角原点）

📏 BarcodeSize（条码尺寸）

字段名	JSON 类型	Rust 类型	单位	必填	说明
`height`	`number`	`f32`	mm	✅	条码高度
`module_width`	`number`	`Option<f32>`	mm	❌	单模块宽度（优先级高）
`width`	`number`	`Option<f32>`	mm	❌	整体宽度

🔤 HumanReadableText（条码附属文本）

字段名	JSON 类型	Rust 类型	说明
`enabled`	`boolean`	`Option<bool>`	是否显示
`content`	`string`	`Option<String>`	显示内容（覆盖条码数据）
`font_size`	`number`	`Option<f32>`	字号 (pt)
`font_name`	`string`	`Option<String>`	字体名称
`color`	`string`	`Option<String>`	文字颜色 Hex
`bold`	`boolean`	`Option<bool>`	是否粗体
`align`	`string`	`Option<String>`	对齐方式：`Left`, `Center`, `Right`
`offset_y`	`number`	`Option<f32>`	Y 轴偏移量 (mm)
`side`	`number`	`Option<i32>`	显示位置：0=下方, 1=上方

🔤 TextElement（独立文本）

字段名	JSON 类型	Rust 类型	单位	说明
`x`	`number`	`Option<f32>`	mm	X 坐标
`y`	`number`	`Option<f32>`	mm	Y 坐标
`content`	`string`	`Option<String>`	-	文本内容
`label`	`string`	`Option<String>`	-	标签标识
`font_size`	`number`	`Option<f32>`	pt	字号
`font_name`	`string`	`Option<String>`	-	字体名称
`color`	`string`	`Option<String>`	-	颜色 Hex
`bold`	`boolean`	`Option<bool>`	-	粗体
`line_spacing`	`number`	`Option<f32>`	pt	行间距
`width`	`number`	`Option<f32>`	mm	文本框宽度
`height`	`number`	`Option<f32>`	mm	文本框高度
`overflow`	`string`	`Option<String>`	-	溢出处理：`clip`, `ellipsis`
`v_align`	`string`	`Option<String>`	-	垂直对齐：`Top`, `Middle`, `Bottom`
`direction`	`number`	`Option<i32>`	-	文字方向 (0=水平)

➖ Line（线条）

字段名	JSON 类型	Rust 类型	单位	说明
`x1`	`number`	`Option<f32>`	mm	起点 X
`y1`	`number`	`Option<f32>`	mm	起点 Y
`x2`	`number`	`Option<f32>`	mm	终点 X
`y2`	`number`	`Option<f32>`	mm	终点 Y
`thickness`	`number`	`Option<f32>`	mm	线条粗细
`color`	`string`	`Option<String>`	-	颜色 Hex

🖼️ ImageElement（图片）

字段名	JSON 类型	Rust 类型	单位	说明
`x`	`number`	`Option<f32>`	mm	X 坐标
`y`	`number`	`Option<f32>`	mm	Y 坐标
`width`	`number`	`Option<f32>`	mm	显示宽度
`height`	`number`	`Option<f32>`	mm	显示高度
`image_name`	`string`	`Option<String>`	-	预加载图片名称
`image_path`	`string`	`Option<String>`	-	服务端图片路径
`base64`	`string`	`Option<String>`	-	Base64 编码图片数据

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

⬜ Rectangle（矩形）

字段名	JSON 类型	Rust 类型	单位	说明
`x`	`number`	`Option<f32>`	mm	X 坐标
`y`	`number`	`Option<f32>`	mm	Y 坐标
`width`	`number`	`Option<f32>`	mm	宽度
`height`	`number`	`Option<f32>`	mm	高度
`thickness`	`number`	`Option<f32>`	mm	边框粗细
`color`	`string`	`Option<String>`	-	边框/填充颜色
`fill`	`boolean`	`Option<bool>`	-	是否填充
`radius`	`number`	`Option<f32>`	mm	圆角半径

⚠️ 错误码说明

错误码	触发条件	表现
E002	`pdf_profile` 为不支持的非空值	PDF 上覆盖红色 "E002" 层
E003	严格模式下缺失必填 metadata	PDF 上覆盖 "E003" 层并列出缺失字段

📝 完整示例

json

[
  {
    "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-03
📌 生成者: Claude (Anthropic)

xPdf API 完整接口文档 ​

📋 概述 ​

🏗️ 数据结构总览 ​

📦 LabelRequest（根对象） ​

📄 PdfParams（PDF 配置） ​

页面尺寸 ​

文件输出控制 ​

PDF 元数据 (Metadata) ​

PDF/A 合规配置 ​

📦 Item（内容容器） ​

📊 OneDParams（一维条码） ​

📱 TwoDParams（二维码） ​

📍 Position（位置） ​

📏 BarcodeSize（条码尺寸） ​

🔤 HumanReadableText（条码附属文本） ​

🔤 TextElement（独立文本） ​

➖ Line（线条） ​

🖼️ ImageElement（图片） ​

⬜ Rectangle（矩形） ​

⚠️ 错误码说明 ​

📝 完整示例 ​