Czym jest Peppol BIS 3.0? Praktyczne wprowadzenie dla deweloperów

Jeśli tworzysz oprogramowanie fakturujące w Europie, prędzej czy później natkniesz się na Peppol.

Dla wielu deweloperów pierwsze spotkanie jest dezorientujące: XML wszędzie, dziwne identyfikatory, odkrywanie SMP i SML, faktury UBL, reguły EN16931, błędy walidacyjne z kryptycznymi komunikatami.

Ten artykuł wyjaśnia Peppol BIS Billing 3.0 z praktycznej perspektywy inżynierskiej. Bez firmowego żargonu. Tylko te części, które deweloperzy naprawdę muszą rozumieć.

Czym jest Peppol?

Peppol to europejska sieć interoperacyjności do wymiany elektronicznych dokumentów biznesowych. Najczęstszym przypadkiem użycia jest fakturowanie elektroniczne.

Zamiast wysyłania PDF-ów e-mailem, dostawcy przesyłają ustrukturyzowane dokumenty faktur bezpośrednio między systemami. Faktura Peppol jest czytelna maszynowo, zestandaryzowana, walidowana i przetwarzalna automatycznie.

Dzięki temu systemy księgowe i platformy ERP mogą przetwarzać faktury przy minimalnym nakładzie ręcznej pracy.

Co oznacza BIS 3.0?

BIS oznacza Business Interoperability Specifications (Specyfikacje Interoperacyjności Biznesowej). Peppol BIS Billing 3.0 definiuje:

• strukturę faktury
• wymagane pola
• reguły walidacyjne
• dozwolone listy kodów
• oczekiwania transportowe

Składnia oparta jest na UBL 2.1 i EN16931. W praktyce: EN16931 definiuje semantyczny model faktury, UBL definiuje składnię XML, a Peppol dodaje na wierzchu reguły interoperacyjności. Więcej o semantycznym modelu EN16931 dowiesz się z artykułu Understanding EN16931.

Dlaczego Europa zmierza ku obowiązkowemu e-fakturowaniu

Wiele krajów UE zmierza ku obowiązkowemu fakturowaniu elektronicznemu. Przykłady to Belgia, Niemcy, Francja, Polska i Włochy. Rządy chcą ograniczenia oszustw VAT, automatycznego przetwarzania podatków, interoperacyjnych zamówień publicznych i zestandaryzowanej wymiany faktur.

Oznacza to, że wiedza o Peppol staje się wiedzą o infrastrukturze.

Jak wygląda faktura Peppol?

Faktura Peppol to dokument XML UBL 2.1.

<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#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1
  </cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
  <cbc:ID>INV-2025-001</cbc:ID>
  <cbc:IssueDate>2025-11-12</cbc:IssueDate>

  <cac:AccountingSupplierParty>
    <!-- seller details -->
  </cac:AccountingSupplierParty>

  <cac:AccountingCustomerParty>
    <!-- buyer details -->
  </cac:AccountingCustomerParty>

  <cac:LegalMonetaryTotal>
    <!-- totals -->
  </cac:LegalMonetaryTotal>
</Invoice>

W przeciwieństwie do PDF-ów, te dokumenty mają być konsumowane przez oprogramowanie. Jedno nieprawidłowe pole może spowodować odrzucenie.

Rola EN16931

EN16931 to europejski semantyczny standard fakturowania. Definiuje takie pojęcia jak numer faktury, kwota VAT, identyfikator nabywcy, warunki płatności i podziały podatkowe. Peppol BIS 3.0 buduje się na tym semantycznym modelu.

Właśnie dlatego deweloperzy często widzą odniesienia takie jak BT-10, BT-49 i BR-CO-10. Są to terminy biznesowe i reguły biznesowe zdefiniowane przez EN16931.

Typowe problemy deweloperów

Większość implementacji Peppol napotyka w końcu te same problemy.

Problemy z przestrzeniami nazw. UBL używa wielu przestrzeni nazw XML. Błędne deklaracje powodują kryptyczne błędy parsera jeszcze przed uruchomieniem jakiejkolwiek logiki biznesowej.

Błędy walidacyjne. Błędy walidacji Schematron mogą być trudne do zdebugowania. Komunikaty o błędach odwołują się do kodów BR, których interpretacja wymaga lektury specyfikacji EN16931.

Formaty identyfikatorów. Identyfikatory uczestników i punktów końcowych są ścisłe. Belgijska firma używająca schematu numeru przedsiębiorstwa 0208 musi poprzedzić go dokładnie tym kodem schematu.

Podpisy XML. Problemy z kanonizacją często psują walidację podpisu. To szczególnie nieprzyjemna kategoria błędów, bo XML wygląda poprawnie podczas odczytu, podpis jest prawidłowy, ale nie weryfikują się nawzajem. Szczegóły znajdziesz w artykule XML signature validation pitfalls in Peppol.

Profile krajowe. Niemcy, Belgia i Francja nakładają dodatkowe wymagania ponad podstawową specyfikację Peppol BIS 3.0. Dokument prawidłowy dla jednego kraju może być nieprawidłowy dla innego.

Odkrywanie SMP i SML

Peppol używa mechanizmu odkrywania podobnego do DNS. Przepływ działa mniej więcej tak:

1. Skróć identyfikator uczestnika.
2. Zbuduj nazwę hosta DNS ze skrótu.
3. Zapytaj SML (Service Metadata Locator) w celu znalezienia SMP uczestnika.
4. Zapytaj SMP (Service Metadata Publisher) w celu pobrania metadanych usługi.
5. Określ obsługiwane typy dokumentów i adresy URL punktów końcowych.
6. Dostarcz dokument przez Access Point.

Sama odpowiedź SMP jest podpisanym dokumentem XML. To właśnie ten podpis powoduje wspomniane problemy z kanonizacją.

Dlaczego faktury PDF nie wystarczają

Tradycyjne faktury PDF są czytelne dla człowieka. Faktury Peppol są czytelne maszynowo. Wiele nowoczesnych systemów łączy oba: PDF/A-3 do reprezentacji wizualnej, osadzony XML do automatyzacji.

To jest fundament Factur-X i ZUGFeRD. Porównanie tego, jak te formaty odnoszą się do siebie, znajdziesz w artykule Factur-X vs ZUGFeRD vs XRechnung vs Peppol.

Trudna część

Generowanie prawidłowego XML UBL nie jest trudną częścią. Trudna część to generowanie XML, który przeżyje rzeczywistą interoperacyjność:

• Walidacja Schematron przez wiele krajowych zestawów reguł
• Odkrywanie SMP z dynamicznymi prefiksami przestrzeni nazw
• Weryfikacja podpisu XML na dokumentach, które zostały ponownie zserializowane
• Pola obowiązkowe specyficzne dla danego kraju, nieobecne w podstawowej specyfikacji
• Reguły zaokrąglania, które dają różne wyniki w zależności od tego, czy zaokrąglasz na poziomie pozycji czy dokumentu

W kolejnych artykułach omówimy: EN16931 szczegółowo, UBL kontra CII, wewnętrzne mechanizmy odkrywania SMP, pułapki podpisów XML i typowe błędy walidacji Peppol.

Prawdziwy koszt trudnej części to nie czytanie specyfikacji. To nakład operacyjny: aktualizowanie zestawów reguł Schematron przy każdym wydaniu Peppol BIS, graceful handling błędów odkrywania SMP, utrzymywanie wariantów reguł krajowych dla Niemiec, Belgii, Francji i Polski.

SealDoc to API obsługujące tę warstwę. Przesyłasz dane faktury jako ładunek JSON. API generuje dokument UBL, uruchamia walidację Schematron EN16931 i Peppol BIS 3.0, wykonuje odkrywanie SMP, owija dokument w kopertę AS4 i dostarcza go do Access Pointa odbiorcy. Jeśli odbiorca nie jest osiągalny lub dokument nie przejdzie walidacji, otrzymujesz ustrukturyzowany błąd wskazujący dokładnie, który krok zawiódł i dlaczego.

Do testowania i debugowania publiczny walidator SealDoc akceptuje pliki faktur UBL i CII i zwraca zwykłojęzyczny raport z każdej naruszonej reguły EN16931 i Peppol BIS 3.0, z numerem BT i kodem reguły biznesowej. Nie jest wymagane konto.