Rozumienie EN16931: europejski model danych faktury

EN16931 to europejska norma definiująca, co musi zawierać faktura elektroniczna. To nie jest format XML. To semantyczny model danych. Każdy główny europejski format e-fakturowania, czy to Peppol BIS Billing 3.0, Factur-X, ZUGFeRD czy XRechnung, jest implementacją EN16931 w określonej składni XML.

Zrozumienie EN16931 oszczędza czas przy debugowaniu błędów walidacji, wyjaśnianiu wymagań integracyjnych dostawcom ERP lub implementowaniu nowego profilu faktury od zera.

Co tak naprawdę określa EN16931

EN16931 składa się z dwóch części:

EN 16931-1 definiuje semantyczny model danych: jakie elementy danych może zawierać faktura, które są obowiązkowe i jakie są reguły biznesowe
EN 16931-2 definiuje powiązania składni: jak model semantyczny mapuje na XML UBL 2.1 i UN/CEFACT CII XML

Efektem jest to, że faktura Peppol BIS Billing 3.0 UBL i faktura Factur-X CII mogą reprezentować tę samą fakturę biznesową. Zawartość semantyczna jest identyczna. Składnia XML jest zupełnie różna.

Terminy Biznesowe i Grupy Biznesowe

EN16931 organizuje dane faktury w Grupy Biznesowe (BG) i Terminy Biznesowe (BT).

Grupa Biznesowa to zbiór powiązanych terminów. Termin Biznesowy to pojedynczy element danych z zdefiniowanym identyfikatorem, nazwą, karnością i typem danych.

Najważniejsze grupy na najwyższym poziomie:

Grupa	Zawartość
BG-2 Kontrola procesu	Identyfikator specyfikacji (BT-24), typ procesu biznesowego (BT-23)
BG-4 Sprzedawca	Nazwa, adres, numer VAT, rejestracja prawna
BG-7 Nabywca	Nazwa, adres, identyfikator referencyjny, adres elektroniczny
BG-22 Sumy dokumentu	Podstawa opodatkowania, suma faktury, kwota VAT, kwota należna
BG-25 Pozycja faktury	Ilość, cena jednostkowa, stawka VAT, kwota netto pozycji

Pełny model obejmuje ponad 150 BT w różnych grupach. Większość implementacji potrzebuje tylko podzbioru, ale walidacja dokumentu wymaga wiedzy, które BT są obowiązkowe dla docelowego profilu.

Terminy Biznesowe, na których potykają się deweloperzy

Większość błędów walidacji pochodzi z małego zestawu BT, które są albo źle rozumiane, albo słabo udokumentowane w przewodnikach implementacyjnych.

BT-24: Identyfikator specyfikacji

Musi to być specyficzny URI identyfikujący, do którego profilu faktura twierdzi, że jest zgodna. Dla Peppol BIS Billing 3.0:

urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1

Błędne ustawienie tego powoduje, że walidator odbiorcy odrzuca fakturę zanim sprawdzi zawartość jakiegokolwiek pola. Każdy profil (baza EN16931, Peppol BIS 3.0, Peppol BIS 3.0 z rozszerzeniem krajowym) ma inny URI.

BT-10: Numer referencyjny nabywcy

Używany różnie w różnych krajach. W Niemczech przenosi Leitweg-ID, obowiązkowy identyfikator routingu dla faktur B2G. W większości innych krajów jest to wewnętrzne odniesienie do zamówienia zakupu lub pozostaje puste. Pole jest opcjonalne w bazie EN16931, ale obowiązkowe w niemieckim profilu krajowym.

BT-49: Elektroniczny adres nabywcy

Identyfikator uczestnika Peppol nabywcy. Format: schemat:identyfikator. Dla belgijskiej firmy identyfikowanej numerem przedsiębiorstwa:

<cbc:EndpointID schemeID="0208">0468863455</cbc:EndpointID>

Wymagane przy przesyłaniu przez sieć Peppol. Wiele implementacji pomija to w fakturach B2B poza Peppol, co jest akceptowalne w bazie EN16931, ale nieprawidłowe w profilach Peppol BIS.

BT-131: Kwota netto pozycji faktury

Kwota netto dla pojedynczej pozycji, obliczona jako ilość razy cena jednostkowa pomniejszona o ewentualne obniżki na poziomie pozycji. Reguła biznesowa EN16931 BR-CO-10 wymaga, aby suma wszystkich wartości BT-131 była równa BT-106 (suma kwot netto pozycji faktury).

Zaokrąglanie ma tu znaczenie. Norma oczekuje, że arytmetyka jest wykonywana na surowych wartościach i zaokrąglana na poziomie agregatu, a nie per pozycję. Zaokrąglanie każdej pozycji niezależnie i następne sumowanie daje rozbieżności, które nie przechodzą BR-CO-10 przy dużych ilościach.

BT-110: Kwota podatku kategorii VAT

Kwota VAT na kategorię podatkową. Reguła EN16931 BR-CO-15 wymaga, aby suma faktury pomniejszona o podstawę opodatkowania była równa sumie wszystkich BT-117 (kwot podatku kategorii VAT). Błędy tutaj są często powodowane arytmetyką zmiennoprzecinkową lub przedwczesnym zaokrąglaniem.

Reguły Biznesowe: warstwa walidacyjna

Reguły Biznesowe (BR) to formalne ograniczenia wyrażone w Schematron. Istnieją dwie kategorie.

Reguły strukturalne wymuszają obecność pól i format:

BR-01: An Invoice shall have a Specification identifier (BT-24).
BR-02: An Invoice shall have an Invoice number (BT-1).
BR-04: An Invoice shall have an Invoice currency code (BT-5).

Reguły obliczeniowe wymuszają spójność arytmetyczną:

BR-CO-10: Sum of Invoice line net amount (BT-106) = sum of all BT-131 values.
BR-CO-15: Invoice total VAT amount (BT-110) = sum of all BT-117 values.
BR-CO-16: Amount due for payment (BT-115) = Invoice total with VAT (BT-112)
          - Paid amount (BT-113) + Rounding amount (BT-114).

Peppol BIS 3.0 dodaje reguły rozszerzeń krajowych ponad reguły bazy EN16931. Przykłady:

BR-DE-TMP-32: Delivery date (BT-72) is required for German B2G invoices.
BR-DE-18:     VAT identifier of the seller (BT-31) or tax registration (BT-32)
              shall be present.

Te reguły rozszerzeń różnią się w zależności od profilu krajowego i są publikowane przy każdym wydaniu Peppol BIS.

Jak EN16931 mapuje na UBL i CII

Dwie składnie XML obsługują te same BT, ale używają zupełnie różnych nazw elementów i struktur. Właśnie dlatego kod parsujący faktury UBL nie może parsować faktur CII bez osobnej implementacji, nawet jeśli obie są zgodne z EN16931.

Nazwa sprzedawcy (BT-27) w obu składniach:

UBL 2.1:

<cac:AccountingSupplierParty>
  <cac:Party>
    <cac:PartyName>
      <cbc:Name>Acme GmbH</cbc:Name>
    </cac:PartyName>
  </cac:Party>
</cac:AccountingSupplierParty>

UN/CEFACT CII:

<ram:SellerTradeParty>
  <ram:Name>Acme GmbH</ram:Name>
</ram:SellerTradeParty>

Oba mapują na BT-27. Zawartość semantyczna jest identyczna. Ścieżka XML różni się zupełnie.

Peppol BIS 3.0 używa UBL. Factur-X i ZUGFeRD używają CII. XRechnung obsługuje oba. Dokument mapowania EN16931-2 (bezpłatny z CEN/TC 434) zawiera obie ścieżki dla każdego BT i warto go mieć otwartego podczas implementacji.

Walidacja Schematron

Walidacja EN16931 jest zaimplementowana jako reguły Schematron wstępnie skompilowane do XSLT 2.0. Oficjalne zestawy reguł są publikowane przy każdym wydaniu Peppol BIS:

github.com/OpenPEPPOL/peppol-bis-invoice-3/releases

Artefakty zawierają skompilowane pliki XSLT:

peppol-en16931-ubl.xsl    (for UBL invoices)
peppol-en16931-cii.xsl    (for CII invoices)

Uruchomienie któregokolwiek z nich na fakturze zwraca SVRL (Schematron Validation Report Language). Niezaliczona reguła wygląda tak:

<svrl:failed-assert test="..." location="/Invoice/...">
  <svrl:text>
    [BR-CO-10]-Sum of Invoice line net amount (BT-106) = 
    sum of Invoice line net amount (BT-131).
  </svrl:text>
</svrl:failed-assert>

Wymagany jest procesor XSLT 2.0. W .NET standardowym wyborem jest Saxon HE (open source, nie wymaga licencji enterprise). W Javie działają Saxon lub Xerces.

Typowe błędy implementacyjne

Mieszanie ścieżek elementów UBL i CII. Deweloperzy pracujący z oboma formatami wklejają nazwy elementów z niewłaściwego powiązania. Dokument mapowania EN16931-2 temu zapobiega.

Zakładanie, że reguły obecności są takie same w różnych profilach. Pole opcjonalne w bazie EN16931 może być obowiązkowe w Peppol BIS 3.0 lub w rozszerzeniu krajowym. Waliduj względem docelowego profilu, a nie standardu bazowego.

Zaokrąglanie na niewłaściwym poziomie. Oblicz surowe sumy arytmetyczne dla wszystkich pozycji, następnie zaokrąglij agregat. Zaokrąglanie każdej pozycji niezależnie i sumowanie zaokrąglonych wartości daje niezgodności arytmetyczne, które nie przechodzą BR-CO-10, często o kilka groszy na dużych fakturach z wieloma pozycjami.

Nieprawidłowe BT-24 dla docelowego profilu. Każdy profil ma specyficzny URI identyfikatora specyfikacji. Użycie bazowego URI EN16931 na fakturze Peppol BIS 3.0 powoduje natychmiastowe odrzucenie dokumentu przez walidację na poziomie profilu.

Hardkodowanie kodów kategorii VAT. EN16931 definiuje specyficzne wartości kodów dla kategorii VAT (S, Z, E, AE, K, G, O, L, M). Wiele implementacji hardkoduje “S” (stawka standardowa) i psuje się przy przetwarzaniu faktur z odwrotnym obciążeniem lub zerową stawką.

EN16931 to wiedza o infrastrukturze

EN16931 leży u podstaw każdego europejskiego obowiązku e-fakturowania. Gdy wymagania wdrażane są w Belgii, Francji, Niemczech i Polsce, zrozumienie modelu semantycznego staje się coraz ważniejsze dla deweloperów budujących lub utrzymujących systemy fakturowania.

Zrozumienie struktury BT/BG, reguł obliczeniowych i powiązań składni stawia Cię w pozycji, w której możesz debugować błędy walidacji, które w innym przypadku wymagałyby godzin lektury specyfikacji, implementować nowe profile czysto i komunikować się jasno z dostawcami ERP i zespołami ds. zgodności.

Praktycznym problemem jest nie jednorazowe nauczenie się EN16931. Chodzi o utrzymywanie poprawnych implementacji w miarę aktualizacji zestawów reguł przy każdym wydaniu Peppol BIS, gdy rozszerzenia krajowe dodają nowe pola obowiązkowe i gdy przypadki brzegowe zaokrąglania ujawniają się w produkcji z prawdziwymi danymi z prawdziwych systemów ERP.

SealDoc jest dostarczany z zestawami reguł śledzącymi wydania Peppol BIS. Gdy generujesz fakturę przez API SealDoc, dokument jest walidowany względem poprawnego profilu zanim opuści system. BR-CO-10 i BR-CO-15 są wymuszane po stronie serwera, tak by błędy zaokrąglania nie docierały do Twoich nabywców. Gdy otrzymasz błąd walidacji od partnera handlowego, publiczny walidator SealDoc akceptuje dokument i mapuje każde naruszenie z powrotem na konkretny BT i BR, który został naruszony, co skraca czas diagnozy z godzin do minut.

Jeśli implementujesz EN16931 od zera, walidator jest przydatnym narzędziem kalibracyjnym: generuj dokument kandydacki, uruchamiaj przez walidator, naprawiaj to, co raport identyfikuje, powtarzaj.