ZUGFeRD API для гібридних рахунків PDF/A-3b
Генеруйте рахунки ZUGFeRD PDF/A-3b із вбудованим EN 16931 CII XML через публічний маршрут API gPdf E-Invoice Render.
/api/v1/e-invoice/render Запакувати PDF-вивід рахунку як ZUGFeRD PDF/A-3b із вбудованим EN 16931 CII XML після того, як ваша ERP або білінгова система підготувала коректні дані рахунку.
Коли використовувати цю API
- Потрібен нативний вивід ZUGFeRD із публічного маршруту API E-Invoice Render.
- У вашій системі вже є валідний EN 16931 CII XML для рахунку.
- Потрібне пакування PDF/A-3b з метаданими ZUGFeRD і прив’язкою associated file.
- Потрібна чітка sibling page до ширших сторінок e-invoice і Factur-X.
Що вона не замінює
- Потрібна нативна генерація XRechnung або подання на портал.
- Потрібно, щоб gPdf розрахував податки, вивів семантику рахунку або створив XML з бухгалтерських записів.
- Потрібні стандарти, не перелічені в публічному контракті OpenAPI.
Який шлях API викликати
/api/v1/e-invoice/render
E-Invoice Render — типовий шлях для цього сценарію.
/api/v1/e-invoice/capabilities
Використовуйте, коли сценарію потрібен пов’язаний API-шлях, контракт шаблону або перевірка можливостей.
Мінімальний запит
POST /api/v1/e-invoice/render - мінімальна форма пакета ZUGFeRD.
{
"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 через E-Invoice Render.
- Обробку PDF/A-3b profile для hybrid invoice output.
- Вбудовування CII XML як associated file з метаданими ZUGFeRD.
- Inline PDF або object delivery behavior відповідно до документації.
Що контролює ваша система
- Коректність EN 16931 CII XML, дані рахунку, податкову логіку й семантику покупця та продавця.
- Зовнішню валідацію, вимоги отримувача, подання на портал і юридичне тлумачення.
- Поведінку повторних спроб, зберігання, аудиторські докази й доставку клієнту.
Чеклист для робочого запуску
- Встановіть 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.
- Тримайте XRechnung або роботу з поданням на портал поза цим маршрутом API.
Межі заявлених можливостей
- Ця сторінка покриває ZUGFeRD output через E-Invoice Render.
- Вона не заявляє нативну генерацію XRechnung.
- Ваша система відповідає за бізнес-дані рахунку й валідність XML.
ZUGFeRD використовує шлях e-invoice render
ZUGFeRD не є окремим root маршрут API. Він обирається через поле
settings.e_invoice.standard у POST /api/v1/e-invoice/render. Та сама межа
відповідальності зберігається: gPdf пакує PDF/A-3b hybrid invoice; ваша система
відповідає за факти рахунку й валідність XML.
FAQ
- Який маршрут API рендерить ZUGFeRD?
- Використовуйте POST /api/v1/e-invoice/render із settings.e_invoice.standard = zugferd.
- Чи покриває ця сторінка XRechnung?
- Ні. Ця сторінка обмежена публічним контрактом ZUGFeRD. XRechnung тут не заявляється як нативний output.
- Чи створює gPdf CII XML?
- Ваша система надає EN 16931 CII XML і відповідає за його коректність.
- Чи можна перевірити результат?
- Використовуйте ваш процес валідації ZUGFeRD і сторінки gPdf validator для контексту валідації.