E-Invoice API для Factur-X і ZUGFeRD PDF/A-3b
Генеруйте електронні рахунки Factur-X і ZUGFeRD PDF/A-3b із вбудованим EN 16931 CII XML через публічний маршрут API gPdf e-invoice.
/api/v1/e-invoice/render Запакувати читабельний для людини PDF рахунку й наданий сервісом-викликачем EN 16931 CII XML в електронний рахунок Factur-X або ZUGFeRD PDF/A-3b, який можна валідувати зовнішніми еталонними валідаторами PDF/A та e-invoice.
Коли використовувати цю API
- Потрібен вивід Factur-X або ZUGFeRD, а не лише звичайний PDF рахунку.
- Ваша система може надати коректний EN 16931 CII XML для рахунку.
- Потрібне пакування PDF/A-3b, метадані вкладення і e-invoice XMP wiring.
- Потрібно, щоб публічний маршрут API capabilities підтверджував підтримувані стандарти й profiles.
Що вона не замінює
- Потрібен лише звичайний PDF рахунку для клієнта. Використовуйте JSON Render або Template Render.
- Потрібен нативний вивід XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e або GST до того, як OpenAPI перелічить його.
- Очікуєте, що gPdf створить юридично коректний invoice XML із неповних бізнес-даних.
Який шлях API викликати
/api/v1/e-invoice/render
E-Invoice Render — типовий шлях для цього сценарію.
/api/v1/e-invoice/capabilities
Використовуйте, коли сценарію потрібен пов’язаний API-шлях, контракт шаблону або перевірка можливостей.
Мінімальний запит
POST /api/v1/e-invoice/render - мінімальний запит Factur-X PDF/A-3b.
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
Що виконує gPdf
- Пакування Factur-X або ZUGFeRD PDF/A-3b через POST /api/v1/e-invoice/render.
- Вбудовування EN 16931 CII XML, наданого сервісом-викликачем, як associated file.
- Метадані PDF/A-3b wrapper і standard-specific e-invoice XMP wiring.
- Capabilities discovery через GET /api/v1/e-invoice/capabilities.
Що контролює ваша система
- Бізнес-семантику рахунку, податкові правила, ідентифікатори покупця/продавця й коректність EN 16931 XML.
- Вибір, чи Factur-X або ZUGFeRD доречний для процесу отримувача.
- Зовнішнє тестування прийняття з отримувачем, системою автоматизації AP або локальним процесом відповідності.
Чеклист для робочого запуску
- Викликайте /api/v1/e-invoice/capabilities перед припущенням стандарту або profile.
- Валідуйте EN 16931 CII XML перед вбудовуванням.
- Пропускайте вивід через /validator/ або власний процес еталонної валідації.
- Тримайте генерацію звичайного PDF рахунку й юридичне пакування e-invoice окремими в коді.
- Логуйте request IDs, standard, profile, версію джерела XML і докази валідації.
Межі заявлених можливостей
- Нативний публічний e-invoice output — це Factur-X / ZUGFeRD з EN 16931 CII XML.
- Інші національні назви e-invoice є ринковим контекстом, якщо OpenAPI не перелічує їх як підтримувані стандарти.
- gPdf пакує XML, наданий сервісом-викликачем; ваша система залишається відповідальною за бізнес-коректність XML.
Один маршрут API для e-invoice package
Маршрут електронного рахунку існує тому, що цей процес — не просто “відрендерити PDF рахунку”. Він має створити PDF/A-3b wrapper з правильними metadata associated file і standard-specific XMP, вбудувавши EN 16931 CII XML, наданий сервісом-викликачем.
Викликайте POST /api/v1/e-invoice/render, коли потрібний вивід — Factur-X або
ZUGFeRD. Використовуйте GET /api/v1/e-invoice/capabilities, коли інтеграція
хоче підтвердити підтримувані стандарти, profiles, типи документів і формати XML
перед надсиланням роботи.
Що лишається поза gPdf
XML-семантика лишається вашою відповідальністю. gPdf не може знати, чи номер рахунку юридично коректний, чи правильна сума податку, чи ідентифікатор покупця відповідає торговому партнеру, або чи конкретний отримувач прийме варіант бізнес- процесу. Генеруйте й валідуйте XML вище за gPdf, а потім використовуйте gPdf для пакування й рендерингу PDF/A-3b.
Не перетворюйте терміни roadmap на заяви про нативну підтримку
Коректно згадувати XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e або GST як ринковий контекст. Не представляйте ці назви як нативний публічний renderer output, якщо контракт OpenAPI capabilities їх не перелічує.
FAQ
- Які e-invoice стандарти сьогодні мають нативний публічний вивід?
- Публічний нативний вивід — Factur-X і ZUGFeRD PDF/A-3b із вбудованим EN 16931 CII XML. Перевіряйте /api/v1/e-invoice/capabilities для поточного контракту.
- Чи генерує gPdf EN 16931 XML за мене?
- Ні. Ваша система надає XML content. gPdf пакує його в PDF/A-3b e-invoice wrapper із потрібними метаданими вкладення.
- Чи можна надсилати settings.e_invoice до JSON Render?
- Ні. E-invoice packaging належить до POST /api/v1/e-invoice/render. Публічна документація вказує, що settings.e_invoice є route-specific.
- Як валідувати вивід?
- Використовуйте gPdf validator або власний процес еталонної валідації, щоб перевірити і шар PDF/A, і вбудований шар e-invoice XML.