Barcodes and retail
面向 PDF 文档和标签的 PDF417 条码 API
在物流、票务、登机牌风格和文档流程中渲染 PDF417 条码 PDF，同时由你的系统负责 payload 规则。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 物流后端 / 票务后端 / 出行流程 / 文档自动化服务
要解决的问题
把 PDF417 条码 payload 渲染为标签、票据、表单或登机牌风格文档中的矢量 PDF 元素，同时由你的系统负责编码格式和下游验证。
什么时候用这个 API
- 你需要把 PDF417 条码嵌入 PDF 文档或标签。
- 你的系统已经有最终编码 payload，并知道下游扫码要求。
- 你需要通过 Template Render 复用 PDF417 版式。
- 你需要 PDF 输出，而不是独立条码图片。
它不替代什么
- 你需要 gPdf 认证航空、政府、物流或行业 payload 格式。
- 你需要票库存、座位分配或出行预订逻辑。
- 你需要扫码硬件管理。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 票据风格页面上的 PDF417 条码。
{
"pages": [
{
"size": "a6",
"elements": [
{
"type": "text",
"x": 10,
"y": 14,
"content": "Boarding pass sample",
"style": { "font_size": 14, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "pdf417",
"content": "M1DOE/JOHN EABC123 JFKLAX GP 042 001A0001 100",
"x": 10,
"y": 38,
"width": 80,
"height": 28
}
]
}
]
}
gPdf 负责什么
- 在 PDF 输出中渲染矢量 PDF417 条码。
- 绘制条码周围的文档或标签版式。
- 为复用票据或物流版式绑定模板。
- 通过公开 render API 返回二进制 PDF。
你的系统负责什么
- 编码后的 PDF417 payload、行业规则、票务或发货状态和客户身份。
- 扫码验收、实际打印测试和防欺诈。
- 条码触发的任何下游预订、准入或物流操作。
上线前检查
- 用消费该条码的扫码设备或合作方系统验证 PDF417 payload。
- 按生产尺寸和材料打印并扫码。
- 除非目标工作流要求，不要把敏感数据直接放进条码。
- 已批准的复用版式使用 Template Render。
- 把 request ID 与票据、货件或文档 ID 一起记录。
能力边界
- gPdf 渲染 PDF417 条码；不认证行业 payload 格式。
- 票务、出行、身份和物流语义仍由你负责。
- 仍然需要实物扫码验证。
PDF417 是条码，不是业务流程
PDF417 常见于票务、出行、身份和物流流程。gPdf 可以在 PDF 中渲染该条码。payload 格式、身份检查、预订状态和下游验收都在 render API 之外。
Endpoint 选择
默认调用 /api/v1/pdf/render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 PDF417 条码 API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- gPdf 支持 PDF417 吗？
- 支持。公开 barcode format enum 包含 pdf417 和 MicroPDF417 aliases。
- gPdf 可以创建航空登机牌 payload 吗？
- 不可以。gPdf 渲染你发送的 PDF417 值。payload 构建由你的出行或票务系统负责。
- PDF417 可以配合 Template Render 使用吗？
- 可以。当复用版式只应接收 payload 和业务数据时，使用 Template Render。
- 需要做扫码测试吗？
- 需要。PDF417 流程应使用消费端扫码设备和生产打印材料验证。