Barcodes and retail
面向 GS1 物流 PDF 的 SSCC 标签 API
为物流、托盘、箱唛和仓库流程渲染 PDF 中的 SSCC-18 条码标签，同时由你的系统负责 GS1 payload 正确性。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 WMS / 3PL 后端 / 零售物流系统 / 仓库打印服务
要解决的问题
在你的系统已分配 serial shipping container code 并验证其 GS1 语义后，为托盘、箱件或物流单元渲染矢量 PDF 输出的 SSCC-18 条码标签。
什么时候用这个 API
- 你的系统已经负责 SSCC 值和任何相关 application identifiers。
- 你需要带可扫描 SSCC 条码和人可读文本的 PDF 标签。
- 你需要为仓库或 3PL 打印工位复用 SSCC 标签版式。
- 你希望把 SSCC 标签连接到更宽的托盘或仓库标签流程。
它不替代什么
- 你需要 gPdf 提供 GS1 前缀发放、check digit 创建或合规认证。
- 你需要库存或发货状态管理。
- 你需要购买或询价承运商面单。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - SSCC-18 标签条码。
{
"pages": [
{
"size": "label_100_150",
"elements": [
{
"type": "text",
"x": 6,
"y": 8,
"content": "SSCC",
"style": { "font_size": 12, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "sscc-18",
"content": "000123456789012345",
"x": 6,
"y": 28,
"width": 86,
"height": 30,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
gPdf 负责什么
- 在 PDF 页面中渲染矢量 SSCC 条码。
- 处理文本、边框、条码文本和可选模板绑定的标签版式。
- 为打印、存储或仓库重打流程输出 PDF。
- 请求校验失败时返回共享错误 envelope。
你的系统负责什么
- GS1 company prefix、extension digit、serial reference、check digit 和编码 payload。
- 仓库流程规则、扫码验收和标签材料验证。
- 任何消费 SSCC 的 EDI、ASN、承运商或交易伙伴流程。
上线前检查
- 调用 gPdf 前校验 SSCC 值和 check digit。
- 用生产扫码设备和标签纸扫描输出。
- 记录哪些仓库事件会创建和重打 SSCC 标签。
- 已批准的 SSCC 标签版式使用 Template Render。
- 把交易伙伴合规检查留在 render 调用之外。
能力边界
- gPdf 将 SSCC 条码渲染为 PDF；不发放或认证 SSCC 值。
- GS1 和交易伙伴合规仍由你负责。
- SSCC 标签不代表已创建承运商货件。
SSCC 标签是聚焦的条码流程
SSCC 标签比普通托盘标签更窄。核心事实是 serial shipping container code 本身。gPdf 把该 code 渲染进 PDF；你的系统负责 code 分配、GS1 规则和交易伙伴要求。
Endpoint 选择
默认调用 /api/v1/pdf/render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 SSCC 标签 API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- gPdf 可以创建 SSCC 编号吗？
- 不可以。你的系统创建并验证 SSCC 值。gPdf 把它作为条码渲染进 PDF。
- 应该使用哪个条码格式？
- 渲染 SSCC 条码元素时，使用受支持的 SSCC alias，例如 sscc-18。
- 这可以做成模板吗？
- 可以。大多数 SSCC 标签在版式和字段映射批准后，都应迁移到 Template Render。
- 这会认证 GS1 合规吗？
- 不会。gPdf 渲染矢量条码输出。合规和扫码验收是独立责任。