面向 PDF/A-3b 混合发票的 ZUGFeRD API
使用公开的 gPdf E-Invoice Render endpoint 生成带嵌入式 EN 16931 CII XML 的 ZUGFeRD PDF/A-3b 发票。
/api/v1/e-invoice/render 在你的 ERP 或账单系统已经准备好正确发票数据后，把发票 PDF 输出打包成带嵌入式 EN 16931 CII XML 的 ZUGFeRD PDF/A-3b。
什么时候用这个 API
- 你需要公开 E-Invoice Render endpoint 输出原生 ZUGFeRD。
- 你的系统已经有该发票的有效 EN 16931 CII XML。
- 你需要带 ZUGFeRD 元数据和 associated-file wiring 的 PDF/A-3b 打包。
- 你需要一个与更宽泛电子发票页和 Factur-X 页相互补充的清晰页面。
它不替代什么
- 你需要原生 XRechnung 生成或门户提交。
- 你需要 gPdf 计算税额、推断发票语义或从会计记录创建 XML。
- 你需要公开 OpenAPI 合同中未列出的标准。
应该调用哪个 endpoint
/api/v1/e-invoice/render
E-Invoice Render 是这个场景的默认调用路径。
/api/v1/e-invoice/capabilities
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/e-invoice/render - 最小 ZUGFeRD 打包形态。
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "zugferd",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "ZUGFeRD invoice",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf 负责什么
- 通过 E-Invoice Render 完成 ZUGFeRD 打包。
- 处理混合发票输出的 PDF/A-3b profile。
- 将 CII XML 作为 associated file 嵌入，并附带 ZUGFeRD 元数据。
- 按文档提供 inline PDF 或 object delivery 行为。
你的系统负责什么
- EN 16931 CII XML 正确性、发票数据、税务逻辑、买方和卖方语义。
- 外部验证、接收方要求、门户提交和法律解释。
- 重试行为、存储、审计证据和客户交付。
上线前检查
- 设置 settings.e_invoice.standard = zugferd 和 settings.e_invoice.profile = en16931。
- 使用 format = cii 且 encoding = utf8 的 CII XML。
- 将 settings.profile 设为 pdfa-3b，或省略该字段以使用电子发票默认值。
- 使用你的 ZUGFeRD 验证流程校验返回的 PDF。
- 把 XRechnung 或门户提交工作留在此 endpoint 之外。
能力边界
- 本页覆盖通过 E-Invoice Render 输出 ZUGFeRD。
- 它不宣称原生 XRechnung 生成。
- 发票业务数据和 XML 有效性由你的系统负责。
ZUGFeRD 使用 e-invoice render 路径
ZUGFeRD 不是单独的根 endpoint。它通过 POST /api/v1/e-invoice/render 上的 settings.e_invoice.standard 字段选择。
同样的边界仍然适用：gPdf 打包 PDF/A-3b 混合发票；你的系统负责发票事实和 XML 有效性。
Endpoint 选择
默认调用 /api/v1/e-invoice/render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 ZUGFeRD API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- 哪个 endpoint 渲染 ZUGFeRD？
- 使用 POST /api/v1/e-invoice/render，并将 settings.e_invoice.standard 设为 zugferd。
- 这个页面覆盖 XRechnung 吗？
- 不覆盖。本页仅限公开 ZUGFeRD 合同。这里不宣称 XRechnung 是原生输出。
- gPdf 会创建 CII XML 吗？
- EN 16931 CII XML 由你的系统提供，并由你的系统负责其正确性。
- 可以验证结果吗？
- 请使用你的 ZUGFeRD 验证流程，并参考 gPdf validator 页面了解验证语境。