Barcodes and retail
面向矢量 PDF 输出的 DataMatrix 条码 API
在 PDF 标签和文档中渲染 DataMatrix 与 GS1 DataMatrix 条码，适用于商品、医疗、零售和仓库流程。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 商品标签系统 / 仓库后端 / 零售后端 / 受监管商品流程
要解决的问题
把 DataMatrix 或 GS1 DataMatrix payload 渲染成商品标签、仓库标签或文档里的矢量 PDF 条码元素，同时由你的系统负责被编码的业务内容。
什么时候用这个 API
- 你需要在 PDF 文档或标签中放置二维 DataMatrix 条码。
- 你的应用已经知道要编码的标识符、批次、序列号或商品 payload。
- 你需要通过 Template Render 复用 DataMatrix 标签版式。
- 你想要矢量条码输出，而不是把栅格图片贴进 PDF。
它不替代什么
- 你需要 gPdf 提供监管认证、设备标签审批或 GS1 认证。
- 你需要 gPdf 生成业务标识符或检查外部注册库。
- 你需要扫码设备集群管理。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 商品标签上的 GS1 DataMatrix 条码。
{
"pages": [
{
"size": "label_100_100",
"elements": [
{
"type": "barcode",
"format": "gs1-datamatrix",
"content": "(01)09506000134352(10)LOT26A",
"x": 10,
"y": 14,
"width": 34,
"height": 34
},
{
"type": "text",
"x": 10,
"y": 56,
"content": "GTIN 09506000134352\nLOT LOT26A",
"style": { "font_size": 9, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf 负责什么
- 在 PDF 中渲染矢量 DataMatrix 和 GS1 DataMatrix 条码。
- 绘制条码周围的标签或文档版式。
- 为复用的商品或仓库标签绑定模板。
- 为打印、归档或下载流程输出二进制 PDF。
你的系统负责什么
- 编码 payload 内容、应用标识符、序列号、批次和监管文本。
- 扫码测试、模块尺寸校验、标签材料和验收标准。
- 任何消费该条码的行业合规流程。
上线前检查
- 渲染前校验 payload 语法。
- 按生产尺寸、DPI 和材料打印并扫码。
- 测试长标识符和多语言商品标签变体。
- 把认证和监管审核放在 gPdf 之外。
- 对已批准的标签族使用 Template Render。
能力边界
- gPdf 渲染 DataMatrix 条码；不认证监管合规。
- 你的系统负责条码 payload 语义和扫码验收。
- 矢量渲染不能替代实际打印验证。
PDF 中的 DataMatrix 是渲染任务
DataMatrix 条码经常承载商品或物流标识符。关键边界在 payload。gPdf 会根据你发送的值渲染矢量条码；你的系统决定这个值代表什么，以及它是否满足外部要求。
Endpoint 选择
默认调用 /api/v1/pdf/render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 DataMatrix 条码 API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- gPdf 支持 DataMatrix 条码吗？
- 支持。公开 schema 列出了 datamatrix 和 GS1 DataMatrix 条码格式别名。
- gPdf 会校验监管内容吗？
- 不会。gPdf 负责渲染条码；payload 正确性和监管审核由你的系统负责。
- DataMatrix 标签可以用 Template Render 吗？
- 可以。复用标签版式只应接收业务数据时，适合使用 Template Render。
- 还需要做扫码测试吗？
- 需要。必须使用生产打印机、材料和扫码设备验证。