Compliance and archival
面向归档和电子发票流程的 PDF/A-3b API
使用 gPdf 生成 PDF/A-3b 输出，并明确区分 PDF/A-3b 作为归档 profile 与作为电子发票 wrapper 的不同场景。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 合规后端 / 财务系统 / 法务归档 / 审计工作流
要解决的问题
为归档流程生成 PDF/A-3b 文档，并在 PDF/A-3b 需要承载嵌入式 Factur-X 或 ZUGFeRD EN 16931 XML 时选择电子发票 endpoint。
什么时候用这个 API
- 你需要为已渲染文档选择 PDF/A-3b 归档 profile。
- 你需要解释普通 PDF/A 与电子发票打包之间的边界。
- 你的合规工作流会使用 veraPDF 或其他参考引擎验证生成的 PDF。
- 你需要一个公开页面，把 PDF/A-3b 搜索意图导向正确 endpoint。
它不替代什么
- 你需要公开 API 未记录的任意文件附件流程。
- 你想通过 JSON Render 生成 Factur-X 或 ZUGFeRD 电子发票。请使用 E-Invoice Render。
- 你需要 validator API。当前公开 validator surface 是 /validator/ 页面。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/e-invoice/render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 为渲染文档请求 PDF/A-3b 输出。
{
"settings": {
"profile": "pdfa-3b"
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Archive copy",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf 负责什么
- 通过 JSON Render settings 选择 PDF/A profile。
- 在使用 POST /api/v1/e-invoice/render 时进行 PDF/A-3b 电子发票打包。
- 生成适合外部参考引擎验证的可渲染 PDF 输出。
- 明确区分归档 profile 和法律电子发票工作流。
你的系统负责什么
- 留存策略，以及为什么需要 PDF/A-3b。
- 任何业务数据、XML 语义和外部合规验收标准。
- 验证证据、审计记录和渲染后的长期存储。
上线前检查
- 普通 PDF/A-3b 输出选择 JSON Render。
- 需要嵌入 EN 16931 XML 时选择 E-Invoice Render。
- 使用 /validator/ 或你自己的 veraPDF 流程验证 PDF/A 输出。
- 把请求的 profile 和 request ID 与存储文档一并记录。
- 除非公开文档列出支持，否则不要宣称支持任意附件。
能力边界
- PDF/A-3b 是归档 profile；电子发票打包是在其之上的更窄工作流。
- 不要暗示每一种任意嵌入文件流程都受支持。
- Factur-X 和 ZUGFeRD PDF/A-3b 包必须走 e-invoice route。
PDF/A-3b 是 wrapper，不是完整工作流
PDF/A-3b 是 PDF 归档 profile。它重要，是因为它可以作为混合电子发票的 wrapper，但 profile 本身不会让一个文档变成法律电子发票。普通归档文档可以使用 PDF/A-3b，而不嵌入发票 XML。
对于 Factur-X 和 ZUGFeRD，请使用 POST /api/v1/e-invoice/render。该 endpoint 负责电子发票专用元数据和 associated-file wiring。
按意图选择 endpoint
当目标是“把这个文档渲染成 PDF/A-3b”时，使用 JSON Render。当目标是“把这张发票打包成带 EN 16931 CII XML 的 Factur-X 或 ZUGFeRD”时，使用 E-Invoice Render。这个区分可以让代码保持清晰，也避免普通归档任务意外携带电子发票假设。
外部验证
PDF/A 应通过参考引擎验证，而不是依赖营销描述。使用公开 validator 或你自己的验证流水线，并把报告与审计证据一起保存。
常见问题
- PDF/A-3b 一定是电子发票吗？
- 不是。PDF/A-3b 是 PDF 归档 profile。Factur-X 和 ZUGFeRD 电子发票使用 PDF/A-3b 作为嵌入 EN 16931 XML 的 wrapper。
- 哪个 endpoint 创建 PDF/A-3b？
- 普通 PDF/A-3b 使用带 settings.profile 的 POST /api/v1/pdf/render。输出必须是 Factur-X 或 ZUGFeRD 电子发票时，使用 POST /api/v1/e-invoice/render。
- 我可以通过这个页面附加任意文件吗？
- 除非公开 API 文档列出该流程，否则不要假设支持任意附件。本页聚焦已记录的 PDF/A-3b 和电子发票用途。
- 如何验证 PDF/A 输出？
- 使用 /validator/ 或你自己的参考引擎流水线。电子发票还需要同时验证 PDF/A 层和嵌入式 XML 层。