合规与归档
面向 PDF/A-3b 混合发票的 ZUGFeRD API
使用公开的 gPdf E-Invoice Render API 端点生成带嵌入式 EN 16931 CII XML 的 ZUGFeRD PDF/A-3b 发票。
主 API E-Invoice Render
API 端点
/api/v1/e-invoice/render 适用系统 ERP / 账单后端 / 德国财务流程 / 合规自动化服务
要解决的问题
在你的 ERP 或账单系统已经准备好正确发票数据后，把发票 PDF 输出打包成带嵌入式 EN 16931 CII XML 的 ZUGFeRD PDF/A-3b。
什么时候用这个 API
- 你需要公开 E-Invoice Render API 端点输出原生 ZUGFeRD。
- 你的系统已经有该发票的有效 EN 16931 CII XML。
- 你需要带 ZUGFeRD 元数据和 associated-file 绑定的 PDF/A-3b 打包。
- 你需要一个与更宽泛电子发票页和 Factur-X 页相互补充的清晰页面。
它不替代什么
- 你需要原生 XRechnung 生成或门户提交。
- 你需要 gPdf 计算税额、推断发票语义或从会计记录创建 XML。
- 你需要公开 OpenAPI 契约中未列出的标准。
应该调用哪个 API 端点
/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 配置档。
- 将 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 或门户提交工作留在此 API 端点之外。
能力边界
- 本页覆盖通过 E-Invoice Render 输出 ZUGFeRD。
- 它不宣称原生 XRechnung 生成。
- 发票业务数据和 XML 有效性由你的系统负责。
ZUGFeRD 使用 e-invoice render 路径
ZUGFeRD 不是单独的根 API 端点。它通过 POST /api/v1/e-invoice/render 上的 settings.e_invoice.standard 字段选择。
同样的边界仍然适用：gPdf 打包 PDF/A-3b 混合发票；你的系统负责发票事实和 XML 有效性。
常见问题
- 哪个 API 端点渲染 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 页面了解验证语境。