Developer workflows
面向稳定文档合同的模板 PDF API
当复用版式应由一处维护并被 ERP、OMS、WMS 或 SaaS 调用方重复使用时，用稳定 template_id 和 data array 渲染 PDF。
主 API Template Render
ENDPOINT
/api/v1/template-render 适用系统 SaaS 后端 / ERP 集成 / OMS / WMS / 任务队列
要解决的问题
通过发送稳定的 template_id 和业务 data array 来渲染复用 PDF，而不是要求每个调用方在每次请求中描述页面、坐标和版式元素。
什么时候用这个 API
- 文档版式已经批准，并会被多个调用方或任务复用。
- 调用方应该发送业务数据，而不是坐标级 layout JSON。
- 你需要发票、装箱单、快递面单或自定义模板输出。
- 你希望 active template revisions 在调用方之外受控。
它不替代什么
- 你还在设计版式。请在坐标和字段稳定前使用 JSON Render。
- 你需要任意 HTML-to-PDF 转换。
- 你需要带嵌入式 CII XML 的电子发票 PDF/A-3b 打包。
应该调用哪个 endpoint
/api/v1/template-render
Template Render 是这个场景的默认调用路径。
/api/v1/pdf/render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/template-render - 用模板渲染一张发票。
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-001",
"date_of_issue": "2026-05-29",
"date_due": "2026-06-28",
"issuer_name": "Acme Cloud Inc.",
"issuer_address": "88 Harbor Rd, Long Beach, CA",
"bill_to_name": "Receiver Inc.",
"bill_to_address": "123 Main St, Los Angeles, CA",
"subtotal": "$100.00",
"total": "$100.00",
"amount_due": "$100.00",
"items": [
{
"description": "Service A",
"qty": 1,
"unit_price": "$100.00",
"amount": "$100.00"
}
]
}
]
}
gPdf 负责什么
- 通过稳定 template_id 查找模板。
- 用 active template 渲染每个 data item。
- 在公开 endpoint 限制内，将渲染页拼接成单个 PDF。
- 保持共享鉴权、request ID 和错误 envelope 行为。
你的系统负责什么
- 模板选择、字段映射、业务数据和调用方授权。
- 模板发布流程、变更沟通和测试覆盖。
- 批量渲染时的分片、排队和重试。
上线前检查
- 把 template_id 当作不透明的稳定合同。
- 调用 Template Render 前校验 data 字段。
- 为 active template 和代表性数据保留 golden-PDF 测试。
- 按公开 Template Render 限制拆分大批量任务。
- 记录 template_id、request ID 和业务对象 ID，便于追踪。
能力边界
- Template Render 本身不是设计工具；模板必须已经发布。
- gPdf 不会从模板中推断缺失业务数据。
- Template Render 不能替代 E-Invoice Render endpoint。
Template Render 是生产合同层
JSON Render 适合版式设计阶段。版式成为合同时，应使用 Template Render。调用方发送 template_id 和 data；active template 负责文档结构。
这样调用方更轻量，模板变更也更容易评审、测试和发布。
Endpoint 选择
默认调用 /api/v1/template-render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 模板 PDF API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- 什么时候应该用 Template Render，而不是 JSON Render？
- 当版式已经批准，并且调用方只应发送业务数据时，使用 Template Render。
- template_id 是稳定的吗？
- 是。template API 文档将 template_id 描述为面向调用方的稳定标识符。
- 一个请求可以渲染多个 data item 吗？
- 可以，Template Render 在公开 endpoint 限制内接收 data array。
- Template Render 可以创建电子发票吗？
- 不可以。Factur-X 和 ZUGFeRD PDF/A-3b 打包使用 E-Invoice Render endpoint。