面向归档 PDF 生成的 PDF/A API
通过 JSON Render 请求生成用于归档流程的 PDF/A 输出，并清楚区分 PDF/A profile 和电子发票打包。
/api/v1/pdf/render 当业务流程需要便于归档的 PDF 时，从结构化文档请求生成 PDF/A-profile 输出；只有在需要嵌入 XML 发票打包时才选择 E-Invoice Render。
什么时候用这个 API
- 你的流程需要在 render settings 中选择 PDF/A profile。
- 你需要归档发票、对账单、报表或文档输出。
- 你需要一个比 PDF/A-3b 电子发票打包更宽泛的 PDF/A 页面。
- 你可以用自己的归档验收流程验证生成文件。
它不替代什么
- 你需要带嵌入式 EN 16931 CII XML 的 Factur-X 或 ZUGFeRD。请使用 E-Invoice Render。
- 你需要纯验证流程。请使用 validator 页面了解验证语境。
- 你需要在同一请求中同时加密输出和使用 PDF/A。公开 Render API 将 security settings 和 PDF/A profile settings 视为互斥。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/e-invoice/render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 普通 PDF/A 输出设置。
{
"settings": {
"profile": "pdfa-2b"
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Archive-ready document",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf 负责什么
- 在 JSON Render 请求上处理 PDF/A profile settings。
- 渲染包含文本、表格、图片、条码、元数据和 profile 输出的文档。
- 仅通过 E-Invoice Render 路径进行 PDF/A-3b 电子发票打包。
- 返回二进制 PDF，并保持共享错误行为。
你的系统负责什么
- 归档策略、profile 选择、验证流程、留存和法律验收。
- 文档语义、业务数据和任何所需外部证据。
- 存储、访问控制和未来迁移策略。
上线前检查
- 选择你的归档系统或客户要求的 PDF/A profile。
- 将输出送入你的 validator 和留存验收流程。
- 除非公开文档增加兼容合同，否则将 PDF/A 和 security settings 放在不同渲染流程中。
- 需要嵌入 CII XML 时使用 E-Invoice Render。
- 按留存策略保存源数据或返回的 PDF。
能力边界
- PDF/A 输出不等同于法律电子发票打包。
- gPdf 不能替代你的归档验收或 validator 流程。
- 留存和合规解释由你的系统负责。
PDF/A 是一种 profile 选择
对于普通归档文档，PDF/A 通过 render settings 选择。这让工作流保持接近 JSON Render：你的系统描述文档，并设置所需 profile。
电子发票打包不同。当文档需要带嵌入式 CII XML 的 Factur-X 或 ZUGFeRD 时，请使用 E-Invoice Render endpoint。
Endpoint 选择
默认调用 /api/v1/pdf/render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 PDF/A API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- 通用 PDF/A 输出应该使用哪个 endpoint？
- 普通 PDF/A 输出使用 POST /api/v1/pdf/render，并设置合适的 settings.profile 值。
- 什么时候需要 E-Invoice Render？
- 当文档必须是带嵌入式 CII XML 的 Factur-X 或 ZUGFeRD PDF/A-3b 包时，使用 E-Invoice Render。
- gPdf 会验证归档验收吗？
- 不会。gPdf 渲染 PDF/A 输出。你的系统应按归档或客户验收策略验证输出。
- PDF/A 可以和 security settings 组合吗？
- 当前公开 Render API 不支持。settings.profile 和 settings.security 互斥，非法组合会校验失败。