EN 16931 dla programistów: pojęcia biznesowe, reguły i walidacja

EN 16931 definiuje fakturę jako listę numerowanych pojęć biznesowych (business terms: BT-1, BT-2 …) pogrupowanych w grupy biznesowe (BG-23, BG-25 …), z krotnościami i regułami biznesowymi między nimi. Aby wytworzyć zgodny plik, mapują Państwo każde pojęcie na jeden element składni — UBL 2.1 lub UN/CEFACT CII — wypełniają każde pojęcie obowiązkowe, sprawiają, że sumy spełniają reguły obliczeniowe (BR-CO-xx), i sprawdzają wynik opublikowanym Schematronem, zanim opuści Państwa system. Ten przewodnik przechodzi przez to w kolejności, w jakiej napotyka to programista.

Model, nie plik

Część normatywna normy, EN 16931-1, to semantyczny model danych: mówi, co faktura zawiera i co oznacza każdy element, nie narzucając XML. CEN/TS 16931-2 wymienia dwie składnie, które muszą być akceptowane: UBL 2.1 (Invoice i CreditNote) oraz UN/CEFACT Cross Industry Invoice (CII) D16B. Wiązania składniowe w CEN/TS 16931-3 określają, który element niesie które pojęcie. Części 1 i 2 są dostępne bezpłatnie w krajowych jednostkach normalizacyjnych na mocy porozumienia między Komisją Europejską a CEN; wiązania są dokumentami płatnymi, ale wszystko, czego implementujący potrzebuje do walidacji — reguły Schematron — jest publikowane otwarcie przez zespół eInvoicing Komisji na GitHubie. Tło normy, wersje i koncepcję CIUS opisano na stronie EN 16931 w objaśnieniu.

Trzy konsekwencje kształtują implementację:

• Państwa model domenowy powinien nieść pojęcia biznesowe, nie ścieżki XML. Jeden wewnętrzny obiekt faktury mapowany raz na UBL i raz na CII to znacznie mniej pracy niż dwa ręcznie pisane serializatory, a ten sam obiekt obsługuje XRechnung, ZUGFeRD, Factur-X i Peppol BIS, które wszystkie są profilami (CIUS) lub rozszerzeniami EN 16931. Zob. porównanie formatów.
• Krotność jest wymuszana przez Schematron, nie tylko przez XSD. Plik UBL poprawny według XSD, ale bez nazwy sprzedawcy, jest poprawny schematowo i niepoprawny według EN 16931.
• Reguły obliczeniowe są dokładne co do grosza po zaokrągleniu. Arytmetyka zmiennoprzecinkowa gdziekolwiek w potoku prędzej czy później wyprodukuje naruszenie BR-CO.

Obowiązkowe pojęcia biznesowe

Model podstawowy ma niewielki zbiór pojęć obowiązkowych. Każda faktura EN 16931 musi nieść poniższe pojęcia; CIUS taki jak XRechnung czy Peppol BIS dokłada dalsze wymagania (referencja nabywcy, adres elektroniczny sprzedawcy, sposób płatności itd.), które sprawdzają reguły własne tego profilu.

Pełna lista elementów, z krotnością i opisem każdego pojęcia, znajduje się w samej normie EN 16931-1 i jest odtworzona element po elemencie w dokumentacji składni Peppol BIS. Powyższa tabela to robocze minimum, nie zastępstwo dla lektury normy.

Reguły biznesowe

Reguły występują w rodzinach oznaczonych prefiksem. Walidator raportuje identyfikator reguły, więc gdy poznają Państwo rodziny, większość komunikatów o błędach stanie się zrozumiała sama przez się.

BR-xx

Reguły strukturalne: obecność i krotność. BR-01 „An Invoice shall have a Specification identifier (BT-24)” (faktura musi mieć identyfikator specyfikacji); BR-02 „An Invoice shall have an Invoice number (BT-1)” (faktura musi mieć numer faktury); BR-03 data wystawienia; BR-05 waluta; BR-06 nazwa sprzedawcy; BR-07 nazwa nabywcy; BR-16 „An Invoice shall have at least one Invoice line (BG-25)” (faktura musi mieć co najmniej jedną pozycję).

BR-CO-xx

Warunki i obliczenia. BR-CO-10: BT-106 = Σ BT-131. BR-CO-13: BT-109 = BT-106 − BT-107 (upusty) + BT-108 (opłaty). BR-CO-14: BT-110 = Σ BT-117. BR-CO-15: BT-112 = BT-109 + BT-110. BR-CO-16: BT-115 = BT-112 − BT-113 (zapłacono) + BT-114 (zaokrąglenie). BR-CO-17: BT-117 = BT-116 × BT-119 / 100, zaokrąglone do dwóch miejsc. BR-CO-04 wymaga kodu kategorii VAT na każdej pozycji.

BR-S, BR-Z, BR-E, BR-AE, BR-IC, BR-G, BR-O, BR-IG, BR-IP

Jedna rodzina na kod kategorii VAT (BT-118/BT-151): S stawka podstawowa, Z stawka zerowa, E zwolnienie, AE odwrotne obciążenie, K dostawa wewnątrzwspólnotowa, G eksport, O poza zakresem VAT oraz podatki Wysp Kanaryjskich i Ceuty/Melilli. Każda rodzina określa, co musi zawierać podział podatku, gdy istnieje pozycja tej kategorii. BR-AE-01: faktura z pozycją objętą odwrotnym obciążeniem musi zawierać dokładnie jeden podział VAT z kategorią „AE”. BR-S-08: dla każdej stawki podstawowej kwota podlegająca opodatkowaniu w podziale równa się sumie kwot netto pozycji (plus opłaty, minus upusty) w tej stawce.

BR-CL-xx

Reguły list kodowych: kod typu musi pochodzić z UNTDID 1001 (BR-CL-01), waluta z ISO 4217, kraj z ISO 3166-1, jednostki z zaleceń UN/ECE 20 i 21 itd.

UBL-SR-xx, CII-SR-xx

Reguły składniowe: elementy, których wiązanie nie używa, muszą być nieobecne, a elementy ograniczone nie mogą się powtarzać.

Naruszenia reguł mają flagę. Błąd fatalny (fatal) oznacza, że plik nie jest fakturą EN 16931 i odbiorca może go odrzucić; ostrzeżenie (warning) oznacza, że coś jest nietypowe, ale dozwolone. Błędy fatalne należy traktować jak błędy kompilacji.

Minimalna faktura UBL

Poniższy plik spełnia reguły podstawowe dla jednej pozycji ze stawką podstawową 19 %. Przestrzenie nazw są z UBL 2.1; CustomizationID wskazuje czysty profil EN 16931. Prawdziwy plik XRechnung lub Peppol BIS potrzebuje dodatkowo własnego CustomizationID, ProfileID, referencji nabywcy i danych płatności.

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017</cbc:CustomizationID>
  <cbc:ID>RE-2026-0142</cbc:ID>
  <cbc:IssueDate>2026-09-03</cbc:IssueDate>
  <cbc:DueDate>2026-10-03</cbc:DueDate>
  <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
  <cac:AccountingSupplierParty><cac:Party>
    <cac:PostalAddress><cbc:StreetName>Beispielstrasse 1</cbc:StreetName>
      <cbc:CityName>Berlin</cbc:CityName><cbc:PostalZone>10115</cbc:PostalZone>
      <cac:Country><cbc:IdentificationCode>DE</cbc:IdentificationCode></cac:Country>
    </cac:PostalAddress>
    <cac:PartyTaxScheme><cbc:CompanyID>DE123456789</cbc:CompanyID>
      <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:PartyTaxScheme>
    <cac:PartyLegalEntity><cbc:RegistrationName>Beispiel GmbH</cbc:RegistrationName></cac:PartyLegalEntity>
  </cac:Party></cac:AccountingSupplierParty>
  <cac:AccountingCustomerParty><cac:Party>
    <cac:PostalAddress><cbc:CityName>Hamburg</cbc:CityName><cbc:PostalZone>20095</cbc:PostalZone>
      <cac:Country><cbc:IdentificationCode>DE</cbc:IdentificationCode></cac:Country>
    </cac:PostalAddress>
    <cac:PartyLegalEntity><cbc:RegistrationName>Kunde AG</cbc:RegistrationName></cac:PartyLegalEntity>
  </cac:Party></cac:AccountingCustomerParty>
  <cac:TaxTotal>
    <cbc:TaxAmount currencyID="EUR">190.00</cbc:TaxAmount>
    <cac:TaxSubtotal>
      <cbc:TaxableAmount currencyID="EUR">1000.00</cbc:TaxableAmount>
      <cbc:TaxAmount currencyID="EUR">190.00</cbc:TaxAmount>
      <cac:TaxCategory><cbc:ID>S</cbc:ID><cbc:Percent>19</cbc:Percent>
        <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:TaxCategory>
    </cac:TaxSubtotal>
  </cac:TaxTotal>
  <cac:LegalMonetaryTotal>
    <cbc:LineExtensionAmount currencyID="EUR">1000.00</cbc:LineExtensionAmount>
    <cbc:TaxExclusiveAmount currencyID="EUR">1000.00</cbc:TaxExclusiveAmount>
    <cbc:TaxInclusiveAmount currencyID="EUR">1190.00</cbc:TaxInclusiveAmount>
    <cbc:PayableAmount currencyID="EUR">1190.00</cbc:PayableAmount>
  </cac:LegalMonetaryTotal>
  <cac:InvoiceLine>
    <cbc:ID>1</cbc:ID>
    <cbc:InvoicedQuantity unitCode="HUR">10</cbc:InvoicedQuantity>
    <cbc:LineExtensionAmount currencyID="EUR">1000.00</cbc:LineExtensionAmount>
    <cac:Item><cbc:Name>Consulting</cbc:Name>
      <cac:ClassifiedTaxCategory><cbc:ID>S</cbc:ID><cbc:Percent>19</cbc:Percent>
        <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:ClassifiedTaxCategory>
    </cac:Item>
    <cac:Price><cbc:PriceAmount currencyID="EUR">100.00</cbc:PriceAmount></cac:Price>
  </cac:InvoiceLine>
</Invoice>

Prześledźmy sumy według reguł: netto pozycji 10 × 100,00 = 1000,00 (BT-131); Σ pozycji = 1000,00 (BR-CO-10); brak upustów i opłat, więc BT-109 = 1000,00 (BR-CO-13); jeden podział, S przy 19 %, podstawa 1000,00, podatek 190,00 (BR-CO-17); BT-110 = 190,00 (BR-CO-14); BT-112 = 1190,00 (BR-CO-15); nic nie zapłacono z góry, BT-115 = 1190,00 (BR-CO-16).

Artefakty i narzędzia walidacji

Walidujcie Państwo tymi samymi artefaktami, których używają odbiorcy. Nie ma potrzeby reimplementować reguł.

Praktyczny potok uruchamia najpierw XSD (tanie, wyłapuje zniekształconą strukturę), następnie Schematron EN 16931, potem Schematron profilu (XRechnung lub Peppol), a dla formatów hybrydowych — sprawdzenie kontenera PDF/A-3. Proszę wpiąć to w ciągłą integrację z korpusem własnych dokumentów: po jednym na każdą obsługiwaną kategorię VAT, jeden z upustami i opłatami, jedną fakturę korygującą, jeden w walucie obcej z ustawionym BT-6.

Typowe błędy walidacji i ich przyczyny

Większość niepowodzeń wynika z garstki przyczyn. Rozpoznawanie ich po identyfikatorze reguły oszczędza godziny.

• BR-CO-10, BR-CO-13, BR-CO-15 — sumy różnią się o 0,01. Kwoty pozycji zaokrąglono osobno, a sumy obliczono z wartości niezaokrąglonych, lub odwrotnie. Proszę wybrać jeden punkt zaokrąglania (na pozycję, dwa miejsca, w górę od połowy, chyba że profil mówi inaczej) i wyprowadzać każdą sumę z zaokrąglonych kwot pozycji.
• BR-CO-17 — kwota podatku w podziale nie równa się podstawa × stawka. Ta sama przyczyna, zastosowana do podziału VAT. BT-117 należy obliczać z BT-116, a nie sumując VAT na poziomie pozycji.
• BR-S-08 / BR-AE-08 / BR-E-08 — podział dla kategorii istnieje, ale jego podstawa nie zgadza się z pozycjami. Zwykle upust lub opłata na poziomie dokumentu została zastosowana do sum, ale nie dostała kategorii VAT, albo kategoria pozycji i kategoria podziału się różnią.
• BR-AE-02 … BR-AE-04 — odwrotne obciążenie bez identyfikatorów obu stron. Dla kategorii AE muszą być obecne numer VAT sprzedawcy i numer VAT nabywcy (lub rejestracja podatkowa nabywcy).
• BR-E-10 / BR-AE-10 — wymagany jest powód zwolnienia. Podział ze zwolnieniem lub odwrotnym obciążeniem potrzebuje tekstu powodu zwolnienia z VAT (BT-120) lub kodu (BT-121); podział ze stawką zerową (BR-Z-10) — przeciwnie — nie może go nieść.
• BR-CL-xx — kod z niewłaściwej listy. „PCE” nie jest ważną jednostką; „C62” (jeden) lub „H87” (sztuka) są. „EURO” nie jest kodem ISO 4217; „EUR” jest. Kody krajów to dwie wielkie litery.
• BR-CO-09 — identyfikator VAT sprzedawcy bez prefiksu kraju („123456789” zamiast „DE123456789”).
• BR-01 / nierozpoznany CustomizationID — identyfikator profilu jest nieobecny lub wskazuje profil, którego odbiorca nie akceptuje. Peppol i XRechnung wymagają każdy własnego, dokładnego ciągu znaków.
• Reguły profilu (PEPPOL-EN16931-Rxxx, BR-DE-xx) — rdzeń przechodzi, ale CIUS nie: brak referencji nabywcy (BR-DE-15), brak adresu elektronicznego sprzedawcy, brak sposobu płatności lub źle sformatowany Leitweg-ID. Zob. XRechnung i Peppol.

Aby sprawdzić pojedynczy plik bez budowania łańcucha narzędzi, bezpłatny walidator e-faktur sprawdza dokument według reguł danego kraju i raportuje identyfikatory reguł, nie zapisując pliku.

Jak KRONENWERK to obsługuje

OBSŁUGIWANE KRONENWERK generuje dokument ustrukturyzowany w chwili wystawienia faktury i waliduje go, zanim numer zostanie zużyty: XRechnung i ZUGFeRD dla Niemiec, sprawdzane regułami Schematron KoSIT i krzyżowo biblioteką Mustang; Factur-X dla Francji; Peppol BIS Billing 3.0 UBL dla Belgii; FA(3) dla Polski. Kategoria VAT na każdej pozycji jest wyprowadzana z zapisanego werdyktu podatkowego (stawka podstawowa, stawka zerowa, zwolnienie, odwrotne obciążenie, poza zakresem), a nie wpisywana, a numer VAT nabywcy jest sprawdzany w VIES przy wystawieniu, dzięki czemu naruszenia BR-AE i BR-CO-09 nie powstają z wprowadzania danych. Przychodzące pliki XRechnung, ZUGFeRD/Factur-X i UBL są wczytywane jako faktury zakupowe. Przez API POST /invoices/drafts tworzy wersję roboczą, a GET /invoices/{number} odczytuje wystawioną fakturę; wystawienie, a zatem generowanie i walidacja, odbywa się w produkcie. API nie przyjmuje ani nie zwraca surowego XML i nie waliduje plików zewnętrznych — do tego służy walidator. Zob. stronę produktu e-fakturowanie i API fakturowania.