Compliance and archival
面向混合 PDF/A-3b 电子发票的 Factur-X API
通过公开的 E-Invoice Render endpoint 生成带嵌入式 EN 16931 CII XML 的 Factur-X PDF/A-3b 发票。
主 API E-Invoice Render
ENDPOINT
/api/v1/e-invoice/render 适用系统 ERP / 账单后端 / 合规工作流 / 财务自动化服务
要解决的问题
在你的 ERP 或账单系统已经生成正确结构化发票数据之后，把已渲染的发票 PDF 打包成带嵌入式 EN 16931 CII XML 的 Factur-X PDF/A-3b。
什么时候用这个 API
- 你需要公开 E-Invoice Render endpoint 输出原生 Factur-X。
- 你的系统已经有该发票的有效 EN 16931 CII XML。
- 你需要带 Factur-X 元数据和 associated-file wiring 的 PDF/A-3b 打包。
- 你希望通过 capabilities endpoint 确认当前发布的电子发票合同。
它不替代什么
- 你需要 gPdf 为你创建发票业务语义或税务判断。
- 你需要 OpenAPI 未列出的原生 XRechnung、FatturaPA、KSeF、Peppol、ZATCA、NF-e 或其他标准。
- 你需要直接提交到 Chorus Pro 或其他政府门户。
应该调用哪个 endpoint
/api/v1/e-invoice/render
E-Invoice Render 是这个场景的默认调用路径。
/api/v1/e-invoice/capabilities
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/e-invoice/render - 最小 Factur-X 打包形态。
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"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": "Factur-X invoice",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf 负责什么
- 通过 E-Invoice Render 完成 Factur-X 打包。
- 处理混合发票 PDF 的 PDF/A-3b profile。
- 将 CII XML 作为 associated file 嵌入，并附带标准元数据。
- 按文档提供 inline PDF delivery 或 object-delivery job 行为。
你的系统负责什么
- 正确的 EN 16931 CII XML、发票号码、税务逻辑、买卖方数据和适用性判断。
- 外部验证、接收方规则、门户提交和法律解释。
- 存储、审计链路、重试逻辑，以及交付给客户或门户。
上线前检查
- 发送到 gPdf 之前先验证 CII XML。
- 将 settings.profile 设为 pdfa-3b，或省略该字段以使用电子发票默认值。
- 使用 settings.e_invoice.standard = factur_x 和 settings.e_invoice.profile = en16931。
- 将返回的 PDF 送入你的 Factur-X validator 流程。
- 把提交和接收方路由留在 render API 之外。
能力边界
- 原生公开电子发票输出是带 EN 16931 CII XML 的 Factur-X 或 ZUGFeRD。
- gPdf 不向政府或买方门户提交发票。
- 业务、税务和 XML 正确性由你的系统负责。
Factur-X 是电子发票打包流程
Factur-X 将人可读的 PDF 与机器可读的 EN 16931 CII XML 组合在一起。公开的 gPdf endpoint 会把这个组合打包成 PDF/A-3b 输出。它不决定发票语义，也不把文件提交到门户。
Endpoint 选择
默认调用 /api/v1/e-invoice/render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 Factur-X API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- 哪个 endpoint 渲染 Factur-X？
- 使用 POST /api/v1/e-invoice/render，并将 settings.e_invoice.standard 设为 factur_x。
- gPdf 会生成 EN 16931 XML 吗？
- CII XML 由你的系统提供，并由你的系统负责业务正确性。gPdf 负责把它打包进混合 PDF。
- 这个页面支持 XRechnung 吗？
- 不支持。这个页面只覆盖 OpenAPI 中列出的公开 Factur-X 合同。
- gPdf 会把 Factur-X 发票提交到门户吗？
- 不会。提交和接收方路由都在 render API 之外。