Barcodes and retail
面向矢量 PDF 标签的 GS1 条码 API
在 PDF 中渲染矢量 GS1 条码，覆盖 GS1-128、GS1 DataMatrix、GS1 QR、ITF-14 和 SSCC-18 标签流程。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 零售后端 / WMS / 商品目录系统 / 仓库系统
要解决的问题
把 GS1 条码 payload 渲染成矢量 PDF 标签或文档，同时由你的商品、仓库或零售系统负责正确的 application identifiers、check digits 和扫码验收。
什么时候用这个 API
- 你需要把条码模块绘制为矢量 PDF 内容，而不是粘贴位图图片。
- 你的系统已经有正确的 GS1 payload 和人可读解释。
- 你需要在标签或文档中使用 GS1-128、GS1 DataMatrix、GS1 QR、ITF-14 或 SSCC-18 流程。
- 你希望把复用的条码标签版式迁移到 Template Render。
它不替代什么
- 你需要 gPdf 提供 GS1 认证或商品数据语义校验。
- 你需要 gPdf 分配 GS1 公司前缀、GTIN、SSCC 或 check digits。
- 你需要库存或商品主数据管理。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - GS1-128 风格 PDF 条码元素。
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "barcode",
"format": "gs1-128",
"content": "(00)012345678901234567",
"x": 8,
"y": 22,
"width": 86,
"height": 24,
"barcode_text": { "enabled": true, "position": "bottom" }
},
{
"type": "text",
"x": 8,
"y": 56,
"content": "SSCC pallet label",
"style": { "font_size": 10, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf 负责什么
- 在 PDF 输出中渲染矢量条码。
- 将条码与文本、线条、商品数据和标签结构一起排版。
- 为复用的商品、托盘、箱唛和仓库标签提供 Template Render。
- 输出可用于扫码和打印测试的 PDF。
你的系统负责什么
- GS1 application identifiers、company prefixes、GTIN、SSCC 和 check digits。
- 正确的条码数据、商品数据、监管文本和扫码验收测试。
- 打印流程、标签材料、静区和运营 QA。
上线前检查
- 在上游生成 GS1 payload，并保持可测试。
- 用生产打印机和扫码设备打印并扫描。
- 校验静区、模块尺寸、人可读文本和标签材料。
- 标签版式批准后使用 Template Render。
- 明确记录 gPdf 负责渲染条码，但不认证 GS1 合规。
能力边界
- gPdf 渲染矢量 PDF 条码；它不是 GS1 认证机构。
- 调用方负责 GS1 数据语义和 check digits。
- 扫码验收必须在调用方生产环境中验证。
GS1 条码渲染是 PDF 渲染任务
gPdf 负责把条码绘制进 PDF。它不负责判断 GTIN、SSCC 或 application-identifier 序列是否适合你的业务。请把这些逻辑留在 ERP、WMS、商品信息系统或 GS1 工具中。
使用 JSON Render 或 Template Render
当代码直接排布标签或文档时，使用 JSON Render。当条码只是复用标签版式中的一个字段时，使用 Template Render。两种方式下，调用方都发送应该被编码的 payload。
使用真实扫码设备验证
条码是否成功取决于扫码验收，而不是屏幕上看起来是否正确。请使用生产中的打印机、扫码设备和标签材料验证打印输出。
常见问题
- gPdf 会认证 GS1 标签吗？
- 不会。gPdf 在 PDF 中渲染矢量条码图形。GS1 payload 正确性、扫码测试和任何认证流程都由你的团队负责。
- GS1 条码可以配合 Template Render 使用吗？
- 可以。已发布模板可以包含条码字段，调用方只发送复用标签版式所需的变量数据。
- 谁创建 SSCC 或 GTIN？
- 你的商品、仓库或 ERP 系统创建并校验标识符。gPdf 接收 payload 并渲染。
- 为什么要用矢量条码？
- 矢量模块可以避免栅格缩放造成的失真，让标签 PDF 在不同打印 DPI 和缩放级别下更清晰。