面向结构化文档生成的 JSON 转 PDF API
把结构化 JSON DocumentRequest payload 转换成 PDF，支持页面、坐标、文本、表格、条码、元数据和 PDF/A 设置。
/api/v1/pdf/render 在不运行浏览器、不交付 HTML/CSS、不存储客户文件的情况下，把结构化应用数据转换成确定性的 PDF 文档。你的系统发送页面、元素、坐标、设置和业务内容；gPdf 返回 application/pdf 响应。
什么时候用这个 API
- 你的后端已经有结构化数据，并需要 PDF 响应。
- 你希望显式控制页面、坐标、元素、条码和设置，而不是依赖 HTML layout。
- 你需要为发票、标签、报表、对账单或生成包获得可重复输出。
- 你想先在 Playground 测试 payload，再把 token 放进生产环境。
它不替代什么
- 你需要任意 HTML-to-PDF 转换。gPdf 使用 DocumentRequest JSON，不运行浏览器 DOM。
- 你的团队需要稳定的 template_id 合同。版式发布后请使用 Template Render。
- 你需要 Factur-X 或 ZUGFeRD 电子发票打包。请使用 E-Invoice Render endpoint。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 单页 JSON DocumentRequest。
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Hello from gPdf",
"style": {
"font_size": 18,
"font_family": "NotoSans-Regular"
}
}
]
}
]
}
gPdf 负责什么
- 基于 pages 和 elements 渲染 DocumentRequest。
- 处理文本、表格、图片、矢量条码、线条、形状、水印、元数据和 PDF/A 设置。
- 为 Latin、CJK、emoji-capable 以及其他受支持文字提供字体嵌入和 fallback。
- 成功返回二进制 PDF；失败时返回共享的 gPdf error-code envelope。
你的系统负责什么
- 业务数据、字段映射和文档语义。
- Request ID、重试与幂等策略、文件命名，以及响应后的存储。
- 渲染前的任何税务、发票、承运商、合规或客户专属规则。
上线前检查
- 生成并传入 X-Request-Id，便于追踪。
- 发送生产流量前，按 OpenAPI 或文档校验 payload。
- 让 API base URL 可配置，并把 bearer token 存在源码之外。
- 决定输出应该是 inline 还是 attachment mode。
- 为关键版式增加 golden-PDF 测试，让模板或数据变化可见。
能力边界
- 这不是 HTML-to-PDF，也不会运行 Chromium。
- API 渲染你描述的文档；不会从数据中推断法律或业务含义。
- 对于复用版式，Template Render 通常是更好的公开合同。
JSON Render 工作流如何定位
JSON Render 是最低层的公开渲染路径。你的应用直接发送文档结构：页面尺寸、元素、坐标、样式、元数据、输出模式和可选 PDF/A 设置。当文档版式由代码生成，或团队需要像素级控制 PDF 时，这一层最合适。
API 合同是显式的。如果你的系统发送 text element，gPdf 就渲染文本元素。如果发送 barcode element，gPdf 就把条码绘制为矢量 PDF 内容。gPdf 不会从 payload 中读取业务意图，也不会判断发票号码、承运商追踪号或税务字段是否正确。
何时切换到 Template Render
如果同一个版式会被多个系统反复使用，请把它发布为模板，并用 template_id 加 data[] 调用 POST /api/v1/template-render。这样版式所有权不再散落到每个调用方里，也能给 ERP、OMS、WMS 或 SaaS 后端一个稳定的字段合同。
用 JSON Render 创建版式、生成一次性文档和程序化文档。版式固定、每次请求只变化业务数据时，使用 Template Render。
生产形态
在生产环境中，把 PDF 请求当作任何重要 API 调用处理：包含 request ID、设置超时、让重试具备幂等性、记录响应元数据，并且只有在需要留存时才把返回的 PDF 存进你自己的系统。标准 render 响应之后，gPdf 渲染路径是无状态的。
常见问题
- 这是 HTML-to-PDF API 吗？
- 不是。gPdf 接收带 pages、elements、coordinates 和 settings 的结构化 JSON DocumentRequest。它不会运行浏览器，也不会执行任意 HTML/CSS。
- 我应该先调用哪个 endpoint？
- 如果你想直接控制版式，从 POST /api/v1/pdf/render 开始。当版式需要成为稳定 template_id 合同时，再迁移到 POST /api/v1/template-render。
- API 会直接返回 PDF 吗？
- 会。成功渲染返回 application/pdf。错误使用共享 JSON error envelope，包含 API-XXX code 和 req_id。
- 不做集成也能测试吗？
- 可以。用 gPdf Playground 交互式测试 JSON payload，再把同样的 DocumentRequest 形态放进你的后端 client。