API e-faktur dla Factur-X i ZUGFeRD PDF/A-3b
Generuj e-faktury Factur-X i ZUGFeRD PDF/A-3b z osadzonym XML CII EN 16931 przez publiczny endpoint gPdf do e-faktur.
/api/v1/e-invoice/render Spakować czytelny dla człowieka PDF faktury oraz dostarczony przez system wywołujący XML CII EN 16931 w e-fakturę Factur-X albo ZUGFeRD PDF/A-3b, którą można sprawdzić zewnętrznymi silnikami referencyjnymi PDF/A i e-faktur.
Kiedy użyć tej API
- Potrzebujesz wyjścia Factur-X albo ZUGFeRD, a nie tylko zwykłego PDF faktury.
- Twój system może dostarczyć poprawny XML CII EN 16931 dla faktury.
- Potrzebujesz pakowania PDF/A-3b, metadanych pliku powiązanego i powiązań XMP dla e-faktury.
- Chcesz użyć publicznego endpointu capabilities, aby potwierdzić obsługiwane standardy i profile.
Czego nie zastępuje
- Potrzebujesz tylko zwykłego PDF faktury dla klienta. Użyj JSON Render albo Template Render.
- Potrzebujesz natywnego wyjścia XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e albo GST, zanim OpenAPI wymieni je jako obsługiwane.
- Oczekujesz, że gPdf utworzy prawnie poprawny XML faktury z niepełnych danych biznesowych.
Który endpoint wywołać
/api/v1/e-invoice/render
E-Invoice Render to domyślna ścieżka dla tego procesu.
/api/v1/e-invoice/capabilities
Użyj, gdy proces wymaga powiązanej ścieżki API, kontraktu szablonu albo sprawdzenia capabilities.
Minimalny request
POST /api/v1/e-invoice/render - minimalne żądanie 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" }
}
]
}
]
}
Co obsługuje gPdf
- Pakowanie Factur-X albo ZUGFeRD PDF/A-3b przez POST /api/v1/e-invoice/render.
- Osadzanie dostarczonego przez system wywołujący XML CII EN 16931 jako pliku powiązanego.
- Metadane opakowania PDF/A-3b i standardowe powiązania XMP dla e-faktury.
- Odkrywanie możliwości przez GET /api/v1/e-invoice/capabilities.
Co kontroluje Twój system
- Znaczenie biznesowe faktury, reguły podatkowe, identyfikatory nabywcy i sprzedawcy oraz poprawność XML EN 16931.
- Decyzję, czy Factur-X albo ZUGFeRD pasuje do procesu odbiorcy.
- Zewnętrzne testy akceptacji z odbiorcą, systemem automatyzacji AP albo własnym procesem kontrolnym.
Checklist produkcyjny
- Wywołaj /api/v1/e-invoice/capabilities, zanim założysz dostępność standardu albo profilu.
- Zweryfikuj XML CII EN 16931 przed osadzeniem.
- Sprawdź wynik przez /validator/ albo własny pipeline z silnikami referencyjnymi.
- Oddziel w kodzie generowanie zwykłego PDF faktury od prawnego pakowania e-faktury.
- Loguj ID żądań, standard, profil, wersję źródłową XML i dowody walidacji.
Granice deklaracji
- Natywne publiczne wyjście e-faktury to Factur-X / ZUGFeRD z XML CII EN 16931.
- Nazwy innych krajowych e-faktur są kontekstem rynkowym, chyba że OpenAPI wymienia je jako obsługiwane standardy.
- gPdf pakuje XML dostarczony przez system wywołujący; Twój system nadal odpowiada za biznesową poprawność XML.
Jeden endpoint dla pakietu e-faktury
Endpoint e-faktur istnieje dlatego, że ten proces nie polega wyłącznie na „wyrenderowaniu PDF faktury”. Wynik musi być opakowaniem PDF/A-3b z poprawnymi metadanymi pliku powiązanego i XMP właściwym dla standardu, z osadzonym XML CII EN 16931 dostarczonym przez system wywołujący.
Wywołaj POST /api/v1/e-invoice/render, gdy wymaganym wyjściem jest Factur-X
albo ZUGFeRD. Użyj GET /api/v1/e-invoice/capabilities, gdy integracja chce
potwierdzić obsługiwane standardy, profile, typy dokumentów i formaty XML przed
wysłaniem zadania.
Co pozostaje poza gPdf
Semantyka XML pozostaje po Twojej stronie. gPdf nie może wiedzieć, czy numer faktury jest prawidłowy, kwota podatku poprawna, identyfikator nabywcy pasuje do partnera handlowego albo czy konkretny odbiorca zaakceptuje wariant procesu biznesowego. Wygeneruj i zweryfikuj XML wcześniej, a następnie użyj gPdf do pakowania PDF/A-3b i renderowania.
Nie myl terminów roadmapy z natywnym wsparciem
XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e albo GST można omawiać jako kontekst rynkowy. Nie przedstawiaj tych nazw jako natywnego publicznego wyjścia silnika renderowania, chyba że kontrakt capabilities w OpenAPI je wymienia.
FAQ
- Które standardy e-faktur są dziś natywnym publicznym wyjściem?
- Publiczne natywne wyjście to Factur-X i ZUGFeRD PDF/A-3b z osadzonym XML CII EN 16931. Aktualny kontrakt sprawdzaj w /api/v1/e-invoice/capabilities.
- Czy gPdf generuje dla mnie XML EN 16931?
- Nie. Twój system dostarcza treść XML. gPdf pakuje ją do opakowania e-faktury PDF/A-3b z wymaganymi metadanymi pliku powiązanego.
- Czy mogę wysłać settings.e_invoice do JSON Render?
- Nie. Pakowanie e-faktur należy do POST /api/v1/e-invoice/render. Publiczna dokumentacja wskazuje, że settings.e_invoice jest zależne od trasy.
- Jak walidować wynik?
- Użyj walidatora gPdf albo własnego procesu z silnikami referencyjnymi, aby sprawdzić zarówno warstwę PDF/A, jak i osadzoną warstwę XML e-faktury.