面向 Factur-X 和 ZUGFeRD PDF/A-3b 的电子发票 API
通过公开的 gPdf 电子发票 endpoint 生成带嵌入式 EN 16931 CII XML 的 Factur-X 和 ZUGFeRD PDF/A-3b 电子发票。
/api/v1/e-invoice/render 把可读的发票 PDF 和调用方提供的 EN 16931 CII XML 打包成 Factur-X 或 ZUGFeRD PDF/A-3b 电子发票，并可交由外部 PDF/A 与电子发票参考引擎验证。
什么时候用这个 API
- 你需要 Factur-X 或 ZUGFeRD 输出，而不只是普通发票 PDF。
- 你的系统能提供该发票正确的 EN 16931 CII XML。
- 你需要 PDF/A-3b 打包、附件元数据和电子发票 XMP wiring。
- 你希望通过公开 capabilities endpoint 确认支持的标准和 profile。
它不替代什么
- 你只需要普通客户发票 PDF。请使用 JSON Render 或 Template Render。
- 你需要 OpenAPI 列出之前的原生 XRechnung、FatturaPA、KSeF、Peppol、ZATCA、NF-e 或 GST 输出。
- 你期待 gPdf 从不完整业务数据中生成法律意义正确的发票 XML。
应该调用哪个 endpoint
/api/v1/e-invoice/render
E-Invoice Render 是这个场景的默认调用路径。
/api/v1/e-invoice/capabilities
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/e-invoice/render - 最小 Factur-X PDF/A-3b 请求。
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf 负责什么
- 通过 POST /api/v1/e-invoice/render 完成 Factur-X 或 ZUGFeRD PDF/A-3b 打包。
- 把调用方提供的 EN 16931 CII XML 作为 associated file 嵌入。
- 处理 PDF/A-3b wrapper 元数据和特定标准的电子发票 XMP wiring。
- 通过 GET /api/v1/e-invoice/capabilities 发现能力。
你的系统负责什么
- 发票业务语义、税务规则、买卖方标识，以及 EN 16931 XML 正确性。
- 判断 Factur-X 或 ZUGFeRD 是否适合接收方工作流。
- 与接收方、AP 自动化系统或本地合规流程进行外部验收测试。
上线前检查
- 在假设任何 standard 或 profile 之前调用 /api/v1/e-invoice/capabilities。
- 嵌入前先验证 EN 16931 CII XML。
- 用 /validator/ 或你自己的参考引擎流水线验证输出。
- 在代码中区分普通发票 PDF 生成和法律电子发票打包。
- 记录 request ID、standard、profile、XML source version 和验证证据。
能力边界
- 当前原生公开电子发票输出是带 EN 16931 CII XML 的 Factur-X / ZUGFeRD。
- 除非 OpenAPI 将其他国家电子发票名称列为受支持标准，否则它们只是市场语境。
- gPdf 打包调用方提供的 XML；XML 业务正确性仍由你的系统负责。
一个 endpoint 负责电子发票打包
电子发票 endpoint 存在的原因，是这个流程不只是“渲染一份发票 PDF”。它必须生成带正确 associated file 元数据和特定标准 XMP 的 PDF/A-3b wrapper，同时嵌入调用方提供的 EN 16931 CII XML。
当要求输出 Factur-X 或 ZUGFeRD 时，调用 POST /api/v1/e-invoice/render。当你的集成想在发送任务前确认支持的标准、profile、document type 和 XML format 时，调用 GET /api/v1/e-invoice/capabilities。
gPdf 之外仍由你负责的部分
XML 语义仍是你的责任。gPdf 无法判断发票号码是否合法、税额是否正确、买方标识是否匹配交易伙伴，或某个接收方是否接受某种业务流程变体。请在上游生成并验证 XML，再用 gPdf 做 PDF/A-3b 打包和渲染。
不要把路线图术语写成原生支持
讨论 XRechnung、FatturaPA、KSeF、Peppol、ZATCA、NF-e 或 GST 作为市场语境是可以的。但除非 OpenAPI capabilities 合同列出它们，否则不要把这些名称表述成原生公开 renderer 输出。
常见问题
- 现在原生公开输出支持哪些电子发票标准？
- 公开原生输出是带嵌入式 EN 16931 CII XML 的 Factur-X 和 ZUGFeRD PDF/A-3b。当前合同请以 /api/v1/e-invoice/capabilities 为准。
- gPdf 会帮我生成 EN 16931 XML 吗？
- 不会。XML 内容由你的系统提供。gPdf 会把它连同所需附件元数据打包进 PDF/A-3b 电子发票 wrapper。
- 我可以把 settings.e_invoice 发给 JSON Render 吗？
- 不可以。电子发票打包属于 POST /api/v1/e-invoice/render。公开文档说明 settings.e_invoice 是 route-specific。
- 应该如何验证输出？
- 使用 gPdf validator 或你自己的参考引擎流程，同时检查 PDF/A 层和嵌入式电子发票 XML 层。