Compliance и архивирование
ZUGFeRD API для hybrid invoices в PDF/A-3b
Генерируйте ZUGFeRD PDF/A-3b invoices со встроенным EN 16931 CII XML через публичный gPdf E-Invoice Render endpoint.
ОСНОВНАЯ API E-Invoice Render
ENDPOINT
/api/v1/e-invoice/render СИСТЕМЫ ERP / billing backend / German finance workflow / compliance automation service
Задача сценария
Упаковать invoice PDF output как ZUGFeRD PDF/A-3b со встроенным EN 16931 CII XML после того, как ваша ERP или billing system подготовила корректные invoice data.
Когда использовать эту API
- Нужен native ZUGFeRD output из публичного E-Invoice Render endpoint.
- В вашей системе уже есть valid EN 16931 CII XML для invoice.
- Нужны PDF/A-3b packaging с ZUGFeRD metadata и associated-file wiring.
- Нужна понятная sibling page к более широкой e-invoice и Factur-X pages.
Что она не заменяет
- Нужна native XRechnung generation или portal submission.
- Нужно, чтобы gPdf рассчитывал tax, выводил invoice semantics или создавал XML из accounting records.
- Нужны standards, не перечисленные в публичном OpenAPI contract.
Какой endpoint вызывать
/api/v1/e-invoice/render
E-Invoice Render — путь по умолчанию для этого сценария.
/api/v1/e-invoice/capabilities
Используйте, когда сценарию нужен связанный API-путь, контракт шаблона или проверка возможностей.
Минимальный запрос
POST /api/v1/e-invoice/render - минимальная форма ZUGFeRD package.
{
"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
- ZUGFeRD packaging через E-Invoice Render.
- PDF/A-3b profile handling для hybrid invoice output.
- Встраивание CII XML как associated file с ZUGFeRD metadata.
- Inline PDF или object delivery behavior согласно документации.
Что контролирует ваша система
- Корректность EN 16931 CII XML, invoice data, tax logic, buyer and seller semantics.
- External validation, recipient requirements, portal submission и legal interpretation.
- Retry behavior, storage, audit evidence и customer delivery.
Production-чеклист
- Установите settings.e_invoice.standard = zugferd и settings.e_invoice.profile = en16931.
- Используйте CII XML с format = cii и encoding = utf8.
- Установите settings.profile в pdfa-3b или опустите его, чтобы сработал e-invoice default.
- Проверьте возвращенный PDF в вашем ZUGFeRD validation workflow.
- Держите XRechnung или portal submission work вне этого endpoint.
Границы заявлений
- Эта страница покрывает ZUGFeRD output через E-Invoice Render.
- Она не заявляет native XRechnung generation.
- Ваша система отвечает за invoice business data и XML validity.
ZUGFeRD использует e-invoice render path
ZUGFeRD — не отдельный root endpoint. Он выбирается через поле
settings.e_invoice.standard на POST /api/v1/e-invoice/render. Граница
ответственности та же: gPdf упаковывает PDF/A-3b hybrid invoice; ваша система
отвечает за invoice facts и XML validity.
FAQ
- Какой endpoint рендерит ZUGFeRD?
- Используйте POST /api/v1/e-invoice/render с settings.e_invoice.standard = zugferd.
- Покрывает ли эта страница XRechnung?
- Нет. Эта страница ограничена публичным ZUGFeRD contract. XRechnung здесь не заявляется как native output.
- Создает ли gPdf CII XML?
- Ваша система предоставляет EN 16931 CII XML и отвечает за его корректность.
- Можно ли проверить результат?
- Используйте ваш ZUGFeRD validation workflow и страницы gPdf validator как validation context.