gPdf
Przypadki użycia · E-fakturowanie w UE i finanse

E-faktury w UE: PDF/A-3 z osadzonym Factur-X / ZUGFeRD

Generuj e-faktury EN 16931 z JSON — opakowanie PDF/A-3 z osadzonym załącznikiem CII XML, zgodne z Factur-X albo ZUGFeRD. Obie warstwy możesz bezpłatnie zweryfikować na gpdf.com/validator/.

Zadanie do wykonania

Wystawiaj elektroniczne faktury zgodne z UE z JSON DocumentRequest: opakowanie PDF/A-3 czytelne dla zespołu AP oraz osadzony załącznik CII XML zgodny z EN 16931, który organ podatkowy może przetwarzać maszynowo. Jedno wywołanie API musi wytworzyć oba elementy — i oba muszą przejść walidację w silnikach referencyjnych, nie tylko w kontrolerze dostawcy.

Dlaczego gPdf pasuje tutaj

  • POST /api/v1/e-invoice/render — jeden endpoint, który zwraca PDF/A-3 Factur-X albo ZUGFeRD w jednym przebiegu.
  • Opakowanie PDF/A-3b emitowane automatycznie z właściwą przestrzenią nazw XMP, AFRelationship='Alternative' i metadanymi osadzonego pliku zgodnie z bazą Factur-X / ZUGFeRD.
  • EN 16931 CII XML dołączony jako kanoniczne dane strukturalne — czytelne dla narzędzi automatyzacji AP w całej UE.
  • Tryb ścisłej walidacji uruchamia pełne kontrole Schematron asynchronicznie i zwraca artefakt raportu obok PDF.
  • Profile lokalizacji danych (`eu` / `global` / `auto`), aby zespoły AP/AR objęte GDPR mogły utrzymywać artefakty e-faktur w regionach UE.
  • Bezpłatny publiczny walidator na gpdf.com/validator/ uruchamia równolegle veraPDF (warstwa PDF/A) ORAZ Mustang (warstwa CII XML / EN 16931) — niezależna weryfikacja przed podłączeniem produkcji.

Przykładowe żądanie

POST /api/v1/e-invoice/render — minimalne żądanie Factur-X z osadzonym CII XML.

{
  "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": [] }
  ]
}

Zgodność i wymagania techniczne

  • Factur-X 1.0 — wspólna francusko-niemiecka specyfikacja, obowiązkowa dla francuskich faktur B2B od 2026 r. (etapowo).
  • ZUGFeRD 2.x — niemiecka specyfikacja zgodna z EN 16931; obowiązkowa dla odbioru niemieckich faktur B2B od 2025 r.
  • EN 16931 — ogólnoeuropejski model semantyczny e-faktur, który opakowują zarówno Factur-X, jak i ZUGFeRD.
  • PDF/A-3 — format opakowania archiwalnego wymagany do legalnego przechowywania osadzonego załącznika XML (ISO 19005-3).
  • Walidacja: nie ufaj pojedynczej samokontroli dostawcy. Niezależna weryfikacja przez veraPDF (PDF/A) + Mustang (CII XML) to wzorzec audytowy.

Kształt e-faktury w UE i dlaczego składa się z dwóch formatów

Współczesna e-faktura w UE to dwa dokumenty opakowane w jeden plik:

  1. PDF/A-3, który może przeczytać człowiek — numer faktury, pozycje, sumy, branding dostawcy. Specyfikacja PDF/A-3 (ISO 19005-3) jest jedyną odmianą PDF/A, która pozwala umieszczać dowolne załączniki plikowe wewnątrz opakowania archiwalnego.
  2. Załącznik EN 16931 CII XML wewnątrz tego PDF — ta sama faktura wyrażona jako dane strukturalne, które automatyzacja AP, importy ERP i systemy organów podatkowych mogą parsować bez OCR.

Factur-X (Francja) i ZUGFeRD (Niemcy) to ta sama idea pod różnymi krajowymi nazwami. Oba formaty dołączają EN 16931 Cross-Industry Invoice (CII) XML do opakowania PDF/A-3. ZUGFeRD jest obowiązkowy przy odbiorze niemieckich faktur B2B od 2025 r.; Factur-X wchodzi etapowo jako obowiązkowy format wystawiania B2B we Francji w latach 2026-2027.

Jeśli w 2026 r. wysyłasz faktury do klientów francuskich albo niemieckich, jeden z tych dwóch formatów przestaje być opcjonalny.

Dlaczego generowanie od zera jest trudne — i dlaczego gPdf robi to jednym endpointem

Złożenie tego od podstaw obejmuje:

  1. Wygenerowanie bajtów PDF: skład, fonty i układ.
  2. Osobne wygenerowanie CII XML zgodnego z EN 16931.
  3. Poprawne ustawienie przestrzeni nazw XMP PDF/A-3 (urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0# dla Factur-X; przestrzeń nazw ZUGFeRD 2.x jest inna).
  4. Osadzenie XML z AFRelationship="Alternative" zgodnie ze specyfikacją.
  5. Poprawne oznaczenie osadzonego pliku w tablicy /AF PDF/A-3.
  6. Sprawdzenie wyniku przez veraPDF (warstwa PDF/A) ORAZ Mustang (warstwa CII XML) — oba muszą przejść.

Typowy zespół myli się w tym dwa razy, zanim wynik przejdzie oba silniki. API gPdf zamyka wszystkie sześć kroków w jednym wywołaniu POST /api/v1/e-invoice/render. Dostarczasz:

  • settings.e_invoice.standard — factur_x albo zugferd
  • settings.e_invoice.xml.content — Twój CII XML
  • pages[] — widoczny układ faktury
  • cała reszta jest emitowana automatycznie z poprawnymi metadanymi PDF/A-3.

Zobacz §5 dokumentacji E-Invoice API, aby poznać pełny schemat żądania, tryby walidacji (basic kontra strict) i cykl życia zadań asynchronicznych dla ścisłych kontroli.

Weryfikowanie wyniku — wzorzec audytowy

Deklaracja dostawcy “tak, nasz PDF przechodzi PDF/A-3” nie ma wartości, jeśli audytor używa silników referencyjnych. Wzorzec audytowy wygląda tak:

  1. Wygeneruj e-fakturę przez POST /api/v1/e-invoice/render.
  2. Prześlij wynikowy PDF do validator — uruchamia:
    • veraPDF: oficjalną implementację referencyjną utrzymywaną przez PDF Association. Zgodność PDF/A-3.
    • Mustang: niemiecki projekt open source (mustangproject.org), faktyczny referencyjny kontroler Factur-X / ZUGFeRD — wyodrębnia osadzony CII XML, waliduje go względem EN 16931 Schematron i raportuje pole po polu.
  3. Oba raporty wracają obok siebie w tym samym UI. Oba muszą pokazać “Pass”, zanim wyślesz dokument do produkcyjnej automatyzacji AP.

Ten wzorzec ma znaczenie, ponieważ:

  • PDF, który przechodzi veraPDF, ale nie przechodzi Mustang, ma zgodne opakowanie, lecz zniekształcony XML w środku — system AP odrzuca fakturę przy odbiorze.
  • PDF, który przechodzi Mustang, ale nie przechodzi veraPDF, ma poprawny XML, lecz opakowanie archiwalne nie spełnia PDF/A-3 — długoterminowe archiwum go odrzuca.
  • Każda z tych awarii przerywa przepływ end-to-end. Oba silniki muszą przejść.

Walidator jest bezpłatny, nie wymaga logowania i tworzy raporty JSON, które możesz dołączyć do materiału dowodowego QA. To ten sam dwusilnikowy wzorzec, którego firmy audytowe Big Four używają wewnętrznie — gPdf po prostu udostępnia go publicznie.

Poza Factur-X / ZUGFeRD

Jeśli pracujesz także z:

  • FatturaPA (Włochy, obowiązkowe od 2019 r.) — już na roadmapie walidatora.
  • Peppol BIS 3.0 UBL (kraje nordyckie / Benelux / coraz częściej transgranicznie) — roadmapa.
  • KSeF (Polska, obowiązkowe od 2026 r.) — roadmapa.

Endpoint e-faktur gPdf rozszerzy zakres, gdy każdy format przejdzie z etapu “wczesnej roadmapy” do statusu “live w walidatorze i silniku renderowania”. Kształt pozostaje taki sam: jedno żądanie JSON, właściwa przestrzeń nazw XMP i AFRelationship obsłużone wewnętrznie, oba silniki weryfikują wynik przed wysyłką.

TL;DR

  • Jedno wywołanie API → PDF/A-3 + osadzony EN 16931 CII XML.
  • Wybierz Factur-X albo ZUGFeRD przez settings.e_invoice.standard.
  • Zweryfikuj w validator — veraPDF + Mustang równolegle, bezpłatnie.
  • Oba silniki muszą przejść. API gPdf jest zbudowane tak, aby przechodziły; walidator jest publicznym potwierdzeniem.

Czytaj dalej