Invoicing and finance
面向账单和财务系统的发票 PDF API
用 JSON Render 或 Template Render 基于账单数据生成普通发票 PDF，同时把税务和会计逻辑留在你的系统中。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 账单后端 / ERP / 会计系统 / SaaS 应用
要解决的问题
把账单、ERP 或 SaaS 系统中的发票数据转换成可读的 PDF 发票，同时让编号、税务、支付状态和会计语义继续保留在调用方系统中。
什么时候用这个 API
- 你需要给客户、收据、对账单或会计导出生成普通发票 PDF。
- 你的系统已经负责发票号码、税额计算、行项目和支付状态。
- 你想在不运行浏览器的情况下生成表格、合计块、元数据和可选 PDF/A 设置。
- 你希望为复用发票版式提供 template_id 合同。
它不替代什么
- 你需要 Factur-X 或 ZUGFeRD 这类法律电子发票包。请使用 E-Invoice Render。
- 你期待 gPdf 计算税额、校验会计规则或对账支付状态。
- 你想把任意 HTML 发票转换成 PDF，而不是使用结构化 JSON 或模板。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
/api/v1/e-invoice/render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 最小发票抬头和合计。
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 20,
"y": 42,
"content": "Bill to: Example Customer\nAmount due: USD 245.00",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "line",
"x1": 20,
"y1": 62,
"x2": 190,
"y2": 62
}
]
}
]
}
gPdf 负责什么
- 基于 JSON pages 或 template data 渲染发票 PDF。
- 处理文本、表格、合计区块、分页、元数据和可选 PDF/A 输出。
- 为多个系统共用的稳定发票版式提供 Template Render。
- 返回二进制 PDF，并保持一致的 API 错误 envelope。
你的系统负责什么
- 发票号码、支付状态、税额计算、折扣、贷项和账本含义。
- 客户与开票方数据、行项目映射、币种和舍入规则。
- 留存、交付、邮件、付款链接和会计系统对账。
上线前检查
- 确认每一个可见发票字段都映射到源账单数据。
- 测试行项目溢出、长客户名称、多页发票和合计值。
- 决定版式应放在 JSON Render 还是已发布模板中。
- 把普通发票 PDF 生成和法律电子发票打包分开。
- 把 request ID 和输出文件名写入你的发票记录。
能力边界
- 普通发票 PDF 不等同于法律电子发票要求。
- gPdf 渲染发票文档；不计算税额或会计状态。
- Factur-X / ZUGFeRD 输出属于 POST /api/v1/e-invoice/render。
普通发票与电子发票的区别
普通发票 PDF 是客户阅读的文档。它可以由 JSON Render 或 Template Render 生成。你的系统决定发票号码、税额、行项目、币种和支付状态，然后由 gPdf 渲染可见 PDF。
法律电子发票不同。Factur-X 和 ZUGFeRD 将可读的 PDF/A-3b 发票与嵌入式 EN 16931 CII XML 组合在一起。请使用 POST /api/v1/e-invoice/render 生成这种包。
Template Render 通常是生产 endpoint
财务团队通常不希望每个服务都重新构建发票坐标。常见路径是先设计一次发票，把它发布为模板，再给调用方一个稳定的 template_id 和 data schema。JSON Render 仍适合自定义版式、内部工具和模板原型。
把会计逻辑留在上游
gPdf 应接收最终展示值，而不是未决的会计判断。请在调用 render API 之前计算税额、折扣、舍入、支付状态和发票适用性。这样 PDF 输出才是确定的，也能让财务系统继续作为事实来源。
常见问题
- 发票 PDF 和电子发票是一回事吗？
- 不是。普通发票 PDF 是人可读输出。Factur-X 或 ZUGFeRD 电子发票还会把 EN 16931 CII XML 嵌入 PDF/A-3b wrapper。
- 复用发票应该调用哪个 endpoint？
- 当发票版式稳定、调用方只应发送 template_id 和 data 时，使用 Template Render。代码负责版式时使用 JSON Render。
- gPdf 会计算税额吗？
- 不会。你的账单或会计系统在发送渲染数据前计算税额、合计、折扣和支付状态。
- 发票 PDF 可以使用 PDF/A 吗？
- 可以，JSON Render 支持 PDF/A 设置。当发票必须打包为 Factur-X 或 ZUGFeRD 时，请专门使用 E-Invoice Render。