面向电商和 SaaS 支付的收据 PDF API
基于订单、支付、税务和退款数据生成收据 PDF，支持 QR code、条码、PDF/A 设置和可复用模板输出。
/api/v1/pdf/render 把已完成订单、支付、退款和税务数据转换成可邮件发送、存储、打印或附加到客户账号的收据 PDF，而不要求每个调用方都维护 PDF 绘制代码。
什么时候用这个 API
- 你的系统已经负责支付状态、收据编号、税务行和客户数据。
- 你需要用于邮件、账号历史、客服流程或审计导出的收据 PDF。
- 你希望在收据中加入用于查询、退款或自提流程的 QR code 或条码。
- 版式批准后，你需要一个稳定的收据模板。
它不替代什么
- 你需要支付处理或退款执行。gPdf 渲染收据；资金流由你的支付系统负责。
- 你需要法律电子发票打包。Factur-X 或 ZUGFeRD 输出请使用 E-Invoice Render endpoint。
- 你需要 POS 硬件控制或钱箱逻辑。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 带查询 QR code 的紧凑收据。
{
"pages": [
{
"size": "a6",
"elements": [
{
"type": "text",
"x": 10,
"y": 12,
"content": "Receipt R-2026-1001",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 10,
"y": 28,
"content": "Order total: $82.40\nPaid by card ending 4242\nTax: $6.10",
"style": { "font_size": 10, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "qrcode",
"content": "https://example.com/receipts/R-2026-1001",
"x": 10,
"y": 58,
"width": 28,
"height": 28
}
]
}
]
}
gPdf 负责什么
- 基于 JSON Render payload 渲染收据页面。
- 处理文本、合计、商品行、QR code、条码、元数据和可选 PDF/A 设置。
- 当同一收据版式复用时绑定 Template Render。
- 失败时使用共享 gPdf error envelope，成功时输出二进制 PDF。
你的系统负责什么
- 支付授权、扣款、退款、税额计算和收据编号。
- 客户身份、订单状态、币种格式化和留存策略。
- 邮件投递、账号存储和重复开具收据处理。
上线前检查
- 使用稳定收据编号，并为每次渲染传入 X-Request-Id。
- 决定收据应从源数据重新生成，还是首次渲染后存储 PDF。
- 测试长商品名、退款、折扣、多税种行和零金额订单。
- 客服和财务团队批准版式后切换到 Template Render。
- 把支付和税务判断留在渲染请求之外。
能力边界
- gPdf 不处理支付、不计算税额，也不发起退款。
- 收据 PDF 不会自动成为法律电子发票。
- 业务事实由你的系统负责；gPdf 只渲染 PDF 表示。
收据 PDF 是渲染输出
这不是单独的支付或 POS endpoint。你的电商、账单或 POS 后端决定一张收据存在，然后把收据内容以 DocumentRequest 或已发布模板 data 的形式发送给 gPdf。
渲染层应保持确定性。如果客服再次请求同一张收据，你的系统可以按留存策略重放源数据，或返回之前存储的 PDF。
复用收据的模板路径
收据版式通常很快稳定。设计批准后，发布模板，并用收据字段调用 POST /api/v1/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 渲染你发送的值。
- 收据应该用 JSON Render 还是 Template Render？
- 设计版式时使用 JSON Render。收据版式和字段合同稳定后使用 Template Render。
- 收据可以包含 QR code 吗？
- 可以。gPdf 支持 PDF 输出中的 QR code 条码元素。QR code 中编码的 URL 或 payload 由你的系统负责。
- 这和电子发票 API 一样吗？
- 不一样。普通收据 PDF 使用 JSON Render 或 Template Render。Factur-X 和 ZUGFeRD 打包使用 E-Invoice Render endpoint。