Developer workflows
面向队列和任务的批量 PDF 生成 API
通过队列友好的 JSON Render 或 Template Render 流程批量生成 PDF，同时由你的系统负责分片、重试、幂等和存储。
主 API Template Render
ENDPOINT
/api/v1/template-render 适用系统 任务队列 / SaaS 后端 / ERP 导出服务 / 账单 worker
要解决的问题
在队列或定时任务中批量渲染 PDF：把工作拆成安全的请求，将每个文档或模板数据项发送给 gPdf，并在自己的系统中存储或分发返回的 PDF。
什么时候用这个 API
- 你需要在定时任务或事件驱动批处理中生成发票、对账单、标签或报表。
- 你已有稳定模板，并能在 endpoint 限制内发送多个 data item。
- 你需要适合队列的渲染流程，而不是运行浏览器 worker。
- 你可以自行负责去重、重试和输出存储。
它不替代什么
- 你希望 gPdf 充当批处理调度器、队列、存储系统或幂等账本。
- 你需要公开的 rate-limit headers 或服务端 idempotency-key 合同。
- 你想用一个无限大的请求渲染整场活动里的所有文档。
应该调用哪个 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-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
gPdf 负责什么
- 为每个 JSON Render 或 Template Render 请求执行 PDF 渲染。
- 在公开文档限制内处理 Template Render data arrays。
- 返回适合队列 worker 使用的快速无状态渲染响应。
- 保持共享 request ID 和错误 envelope 行为。
你的系统负责什么
- 队列设计、分片、并发、重试、去重和输出存储。
- 业务对象选择、模板选择和交付流程。
- 退避策略、告警，以及部分失败后的恢复。
上线前检查
- 对任务分片，确保每个请求都在公开的 item 和 payload 限制内。
- 每个请求生成一个 X-Request-Id，并映射到你的 job ID。
- 只对网络错误或 5xx 失败做有界指数退避重试。
- 不要在不修改 payload 的情况下重试 4xx 校验失败。
- 按留存策略保存输出 PDF 或源数据。
能力边界
- gPdf 是渲染 API，不是队列层或存储层。
- 当前公开 API 不发布 rate-limit headers，也没有服务端 idempotency keys。
- 你的系统必须让重试本身保持安全。
批量生成是一种集成模式
批量 PDF 生成不是一个单独 endpoint，而是你的队列使用公开渲染 API 的方式。把任务保持在小批量、可观测、可安全重试的范围内。
对于复用版式，Template Render 通常给出最清晰的合同。对于由程序生成的自定义文档，JSON Render 仍然可用。
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 合规仍由你的系统负责。
常见问题
- gPdf 提供单独的批处理任务 API 吗？
- 不提供单独的批处理调度器。请从你自己的队列或 worker 系统调用 JSON Render 或 Template Render。
- Template Render 可以接收多个 data item 吗？
- 可以，但必须在公开 endpoint 限制内。更大的任务应拆成多个请求。
- 谁负责重试？
- 你的系统负责重试、退避、去重和幂等。gPdf 会回传 request ID，便于追踪。
- 一个请求可以渲染很多不同版式吗？
- 版式或 template ID 不同时，请使用独立请求。让每个请求保持简单、可追踪。