Barcodes and retail
面向文档和标签的 QR code PDF API
使用 JSON Render 或模板，在收据、票据、标签、入门材料和文档查询流程的 PDF 中渲染 QR code。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 SaaS 后端 / 电商后端 / 票务后端 / 文档自动化服务
要解决的问题
把 QR code 放进 PDF 文档、标签、收据、票据或表单中，让用户可以扫描由你的系统控制的链接、标识符或查询 token。
什么时候用这个 API
- 你的系统有 URL、token、订单 ID、票据 ID 或查询值需要编码。
- 你需要把 QR code 绘制进 PDF，而不是合成外部位图。
- 你需要通过 Template Render 复用 QR 版式。
- 你希望用同一个 API 路径处理文本、版式、PDF 输出和 QR code 渲染。
它不替代什么
- 你需要 gPdf 提供短链、访问 token 签发或支付链接创建。
- 你需要扫码分析或移动端 App 逻辑。
- 你需要 PDF 输出之外的 QR code。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 带 QR 查询码的文档页面。
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Scan to view this document online",
"style": { "font_size": 14, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "qrcode",
"content": "https://example.com/documents/DOC-2026-001",
"x": 20,
"y": 44,
"width": 32,
"height": 32
}
]
}
]
}
gPdf 负责什么
- 在 PDF 输出中渲染矢量 QR 条码。
- 处理 QR code 周围的文本、版式、收据、票据、标签或文档上下文。
- 为复用 QR 工作流绑定模板。
- 通过公开 render API 交付 PDF 响应。
你的系统负责什么
- 被编码的 URL 或 token、访问控制、过期时间、跳转行为和移动端目标页。
- 扫码测试、用户路径和防欺诈规则。
- 扫描后触发的任何支付、票务、退货或账号操作。
上线前检查
- 确保编码 URL 在文档生命周期内稳定，或可通过重定向维护。
- 测试扫码距离、对比度、尺寸和打印材料。
- 避免把敏感原始数据直接嵌入 QR payload。
- 使用 request ID，并记录每个生成 PDF 对应的业务对象。
- 把稳定 QR 版式迁移到 Template Render。
能力边界
- gPdf 在 PDF 中渲染 QR code；不托管或保护目标地址。
- token 过期、重定向、权限和扫码 UX 由你的系统负责。
- QR code 本身不是支付或票务系统。
QR code 页面仍需要清晰语义
QR code 只是可见载体。生产工作流取决于它背后的目标地址或 token。gPdf 把 QR code 绘制进 PDF；扫描之后发生什么由你的系统负责。
Endpoint 选择
默认调用 /api/v1/pdf/render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 QR code PDF API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- gPdf 会生成 QR code 图片吗？
- gPdf 在 PDF 输出中渲染 QR code 条码元素。公开响应是 PDF，不是独立图片服务。
- 模板中可以使用 QR code 吗？
- 可以。模板可以包含 QR 字段，调用方发送可变 payload 数据。
- QR 目标地址由谁负责？
- URL、token、重定向、权限和过期行为都由你的系统负责。
- QR code 可以包含敏感数据吗？
- 它可以编码你发送的任何内容，但生产系统通常应编码查询 token 或 URL，而不是原始敏感数据。