Invoicing and finance
面向账号和账单导出的对账单 PDF API
生成账号、账单和活动对账单 PDF，支持多页明细、合计、元数据和可选 PDF/A 归档设置。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 账单后端 / 账号系统 / ERP 导出服务 / SaaS 报表服务
要解决的问题
基于期间数据、期初余额、明细行、调整项和合计渲染客户、账号或账单对账单 PDF，让用户可下载一致记录用于查看或留存。
什么时候用这个 API
- 你的系统已经负责余额、对账期间、交易行和合计。
- 你需要用于账号历史、账单摘要或财务流程的 PDF 导出。
- 你需要带页眉、页脚和汇总区的可重复多页输出。
- 你可能需要 PDF/A 输出用于归档流程。
它不替代什么
- 你需要银行连接、账本对账或财务建议。
- 你需要在同一 render 请求中同时使用加密对账单和 PDF/A。公开 Render API 将 security settings 和 PDF/A profile settings 视为互斥。
- 你需要电子发票 XML 打包。该场景请使用 E-Invoice Render endpoint。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 带期间合计的对账单封面页。
{
"settings": {
"profile": "pdfa-2b"
},
"pages": [
{
"size": "letter",
"elements": [
{
"type": "text",
"x": 18,
"y": 20,
"content": "Account Statement",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 18,
"y": 38,
"content": "Period: 2026-05-01 to 2026-05-31\nOpening balance: $1,240.00\nClosing balance: $1,890.25",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf 负责什么
- 为对账单页面渲染 DocumentRequest。
- 处理文本块、表格、合计区、页码、元数据和 PDF/A profile settings。
- 为稳定的对账单版式和字段合同提供 Template Render。
- 输出适合你的系统下载或存储的二进制 PDF。
你的系统负责什么
- 对账期间逻辑、账号余额、交易数据、币种规则和客户身份。
- 归档策略、访问控制、文件命名和安全交付。
- 任何对账、审计批准或受监管的财务表述。
上线前检查
- 测试长交易描述、高行数、空期间和负余额。
- 为每次对账单渲染生成 request ID。
- 决定是按需渲染，还是在期间关闭后存储每份对账单。
- 只有当对账单归档策略要求时才使用 PDF/A。
- 把访问控制和客户认证留在 render API 之外。
能力边界
- gPdf 不计算账号余额，也不对账账本。
- API 渲染对账单 PDF；财务正确性由你的系统负责。
- PDF/A 输出是一项 render 设置，不能替代留存策略。
对账单是期间文档
对账单页面应从一组已经关闭的业务事实开始：账号、期间、期初余额、活动明细、调整项和期末余额。gPdf 不决定这些事实。它把这些事实渲染成用户可下载、系统可存储的 PDF 版式。
处理大量明细行
对于高行数场景，请把对账单设计成带表格区域、汇总区和页码的可重复版式。调试版式时使用 JSON Render。字段合同稳定后迁移到 Template Render。
Endpoint 选择
默认调用 /api/v1/pdf/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 可以计算对账单余额吗？
- 不可以。你的系统发送期间、余额、明细行和合计。gPdf 负责渲染 PDF。
- 对账单 PDF 可以使用 PDF/A 吗？
- 可以，JSON Render 支持 PDF/A profile settings。是否需要 PDF/A 由你的归档策略决定。
- 对账单应该使用 Template Render 吗？
- 版式稳定后通常应该使用。Template Render 让调用方发送期间数据，而不必重复页面坐标。
- gPdf 会存储对账单吗？
- 不会。标准 render 请求返回 PDF 响应。存储和访问控制由你的系统负责。