Przewodnik Peppol dla programistów: BIS Billing, SMP, AS4 i odpowiedzi

Peppol to czteronarożna sieć: oprogramowanie nadawcy (narożnik 1) przekazuje dokument swojemu punktowi dostępowemu (narożnik 2), który odnajduje punkt dostępowy odbiorcy (narożnik 3) przez wyszukiwanie DNS i SMP i dostarcza go przez AS4; narożnik 3 przekazuje go oprogramowaniu odbiorcy (narożnik 4). Dla programisty oznacza to trzy odrębne problemy — wytworzenie dokumentu Peppol BIS Billing 3.0, zaadresowanie go właściwym identyfikatorem uczestnika oraz pozyskanie akredytowanego dostawcy punktu dostępowego, który go przeniesie. KRONENWERK rozwiązuje dwa pierwsze samodzielnie, a trzeci deleguje do Storecove, akredytowanego dostawcy punktu dostępowego.

BIS Billing 3.0 to EN 16931 z ograniczeniami Peppol

Peppol BIS Billing 3.0 to Core Invoice Usage Specification (CIUS) normy EN 16931: każdy dokument zgodny z BIS jest też zgodny z normą europejską, a BIS dodaje wymagania, których sieć potrzebuje do routingu i przetwarzania faktury. Bieżącą publikacją w chwili czytania jest wersja 3.0.21 (wydanie z maja 2026 r.). Wiąże ona model semantyczny z UBL 2.1 Invoice i CreditNote; CII nie jest używany w Peppol do fakturowania.

Identyfikatory, które czynią plik UBL fakturą Peppol BIS, to stałe ciągi znaków:

Poza regułami podstawowymi BIS wymaga adresów elektronicznych sprzedawcy i nabywcy (cbc:EndpointID z schemeID), referencji nabywcy lub referencji zamówienia, sposobu płatności z kodem oraz kilku ograniczeń formatowania. Egzekwuje je Schematron Peppol (PEPPOL-EN16931-UBL.sch) jako reguły o nazwach PEPPOL-EN16931-Rxxx, nałożone na reguły CEN (CEN-EN16931-UBL.sch). Same reguły podstawowe objaśniono w przewodniku EN 16931 dla programistów.

Identyfikatory uczestników

Uczestnik Peppol jest adresowany schematem i wartością, zapisywanymi jako schemat:wartość — na przykład 0208:0123456789 dla belgijskiego numeru przedsiębiorstwa lub 0204:, po którym następuje Leitweg-ID, dla niemieckiego nabywcy z sektora publicznego. Kody schematów pochodzą z listy ISO 6523 International Code Designator utrzymywanej w polityce OpenPeppol Policy for use of Identifiers (wersja 4.4.0, obowiązująca od 1 listopada 2025 r. w chwili czytania). Ten sam identyfikator pojawia się w trzech miejscach i muszą one być zgodne:

1. W dokumencie UBL, jako cac:AccountingCustomerParty/cac:Party/cbc:EndpointID schemeID="0208" (BT-49) i odpowiednik dla sprzedawcy (BT-34).
2. W kopercie (SBDH) jako identyfikatory nadawcy i odbiorcy, w schemacie identyfikatorów iso6523-actorid-upis.
3. We wpisie SMP odbiorcy, gdzie odbywa się wyszukiwanie.

To, którego schematu używa dana firma, zależy od jej kraju i od tego, co zarejestrowała. Belgia rejestruje pod 0208 (numer przedsiębiorstwa), niemiecki sektor publiczny pod 0204, a równolegle istnieją schematy oparte na VAT, takie jak 9925 (BE:VAT) czy 9930 (DE:VAT). Schematy identyfikatorów, ich formaty i sposób znalezienia zarejestrowanego identyfikatora partnera omówiono na stronie identyfikatory Peppol; bezpłatne narzędzie identyfikatora Peppol sprawdza format wartości.

Odnajdywanie: SML, DNS i SMP

Peppol nie ma centralnego katalogu, który odpytuje nadawca. Wysyłający punkt dostępowy odnajduje punkt końcowy odbiorcy dynamicznie:

1. Haszowanie identyfikatora uczestnika. Bieżąca specyfikacja SML (1.3.0) używa rekordu U-NAPTR: wartość identyfikatora jest zamieniana na małe litery, haszowana algorytmem SHA-256, kodowana Base32 z usunięciem końcowych „=” i poprzedza schemat oraz strefę SML. Starsza postać CNAME z haszem MD5 i prefiksem „B-” została usunięta z SML obsługiwanego przez Komisję podczas porządkowania w lutym–marcu 2026 r.
2. Rozwiązanie w strefie SML. Service Metadata Locator to strefa DNS, która mapuje każdego zahaszowanego uczestnika na SMP hostujący jego metadane. Odpowiedź NAPTR zawiera URL SMP.
3. Zapytanie do SMP. Service Metadata Publisher odpowiada na dwa wywołania REST: GET /{participantId} wymienia typy dokumentów, które uczestnik może odbierać, a GET /{participantId}/services/{documentTypeId} zwraca punkt końcowy dla jednego z nich — URL AS4, identyfikator profilu transportowego, certyfikat odbiorcy i identyfikator procesu. Obowiązująca specyfikacja SMP to 1.4.0.
4. Dostarczenie. Wysyłający punkt dostępowy szyfruje i podpisuje komunikat dla tego certyfikatu i wysyła go metodą POST pod ten URL.

W 2026 r. SML zmienił lokalizację. OpenPeppol przejął lokalizator z infrastruktury eDelivery Komisji: środowisko produkcyjne przeniesiono z edelivery.tech.ec.europa.eu na api.sml.prod.tech.peppol.org, a testowy SML (dawniej SMK, acc.edelivery.tech.ec.europa.eu) na api.sml.test.tech.peppol.org. Operatorzy SMP musieli przenieść swoje rejestracje do 31 maja 2026 r., a punkty dostępowe musiały przełączyć wyszukiwania DNS do 31 sierpnia 2026 r. Wyszukiwania uczestników są rozwiązywane pod iso6523-actorid-upis.participant.sml.prod.tech.peppol.org (produkcja) i …sml.test.tech.peppol.org (test).

Transport: AS4 przez punkt dostępowy

Komunikaty przemieszczają się między punktami dostępowymi w profilu Peppol AS4 (wersja 2.0.3, obowiązująca od 22 kwietnia 2024 r.), czyli wymianie ebMS3/AS4 z podpisywaniem i szyfrowaniem opartym na certyfikatach wydawanych przez PKI OpenPeppol. Certyfikaty te posiadają wyłącznie akredytowane punkty dostępowe: aby nim zostać, organizacja podpisuje Peppol Transport Infrastructure Agreement, przechodzi testy zgodności i działa według zasad poziomu usług OpenPeppol. Dlatego większość dostawców oprogramowania, w tym KRONENWERK, korzysta z dostawcy zamiast prowadzić własny punkt dostępowy.

Dokument biznesowy jest opakowany w Peppol Business Message Envelope (SBDH, specyfikacja 2.0.2, obowiązująca od 2 lipca 2026 r.), która przenosi nadawcę, odbiorcę, identyfikator typu dokumentu, identyfikator procesu i identyfikator instancji. Koperta jest tym, na podstawie czego punkt dostępowy prowadzi routing; UBL wewnątrz jest tym, co czyta oprogramowanie odbiorcy. Przy integracji z API dostawcy punktu dostępowego dostawca zwykle buduje kopertę z kilku parametrów, a Państwo dostarczają tylko UBL i identyfikator odbiorcy.

Walidacja i środowisko testowe

Wysyłający punkt dostępowy waliduje każdy dokument względem Schematronu Peppol przed transmisją i odrzuca dokumenty z błędami. Należy najpierw walidować po swojej stronie tymi samymi artefaktami: CEN-EN16931-UBL.sch i PEPPOL-EN16931-UBL.sch, do pobrania z dokumentacji BIS Billing 3.0, uruchamianymi dowolnym procesorem Schematron lub scenariuszem Peppol walidatora KoSIT. Identyfikatory reguł PEPPOL-EN16931-R001 i kolejne nazywają błędy specyficzne dla Peppol; BR-xx i BR-CO-xx nazywają błędy podstawowe.

Do testów end-to-end OpenPeppol prowadzi sieć testową z własnym SML (T-SML), własnym PKI i testowymi identyfikatorami uczestników. Dostawcy punktów dostępowych udostępniają ją jako sandbox: dokumenty tam wysłane są dostarczane wyłącznie do uczestników testowych i nigdy nie docierają do rzeczywistego odbiorcy. Sieć testowa Peppol to właściwe miejsce, by sprawdzić obsługę identyfikatorów i kopertę przed pierwszą fakturą produkcyjną; dokument, który przechodzi walidację, ale jest zaadresowany na identyfikator, którego odbiorca nigdy nie zarejestrował, zawodzi dopiero w chwili wyszukiwania — i to właśnie pokazuje sieć testowa.

Odpowiedzi: poziom komunikatu i poziom faktury

Istnieją dwa rodzaje informacji zwrotnej i nadawca powinien obsługiwać oba.

Potwierdzenie transportowe

Podpisane potwierdzenie AS4 od odbierającego punktu dostępowego dowodzi, że komunikat dotarł do narożnika 3. Nie mówi nic o treści.

Message Level Response (MLR, BIS 3.0)

UBL ApplicationResponse wysyłany przez odbierający punkt dostępowy lub odbiorcę z powrotem do nadawcy, raportujący wynik walidacji: AP przyjęty (brak błędów krytycznych), RE odrzucony (naruszenia zgodności, przetwarzanie zatrzymane), AB potwierdzony bez walidacji. Odbiorca, który znajdzie błędy krytyczne, powinien odrzucić dokument przez MLR, nawet jeśli nikt o to nie prosił.

Invoice Response (BIS 3.2)

Odpowiedź na poziomie biznesowym od nabywcy — przyjęta, odrzucona, zapłacona, warunkowo przyjęta — używana w profilu „fakturowanie z odpowiedzią” (billing:02). Opcjonalna i wdrażana nierównomiernie.

W praktyce: brak potwierdzenia AS4 należy traktować jako niedostarczenie, MLR RE jako wadę dokumentu do poprawienia i ponownego wysłania, a Invoice Response jako zdarzenie biznesowe do pokazania osobie.

Jak KRONENWERK to abstrahuje

OBSŁUGIWANE Z OGRANICZENIAMI KRONENWERK generuje UBL Peppol BIS Billing 3.0 przy wystawieniu belgijskich faktur, z identyfikatorem uczestnika klienta wpisanym do dokumentu i walidowanym względem Schematronu Peppol i CEN, zanim numer faktury zostanie zużyty. KRONENWERK nie jest punktem dostępowym Peppol. Wysyła i odbiera przez Peppol za pośrednictwem akredytowanego dostawcy punktu dostępowego (Storecove), gdy firma zostanie podłączona w Ustawienia → Dostarczanie; odnajdywanie, koperta, transport AS4 i potwierdzenia są wykonywane przez tego dostawcę, a wysyłka produkcyjna zależy od tego konta i jego konfiguracji. Przychodzące faktury UBL odebrane przez dostawcę są wczytywane jako rachunki. KRONENWERK celowo nie zawiera własnego klienta DNS ani SMP: migracja SML w 2026 r. nie wymagała od KRONENWERK niczego, ponieważ wyszukiwanie nigdy nie było jego zadaniem.

Przez API programista tworzy szkic (POST /invoices/drafts) i odczytuje wystawioną fakturę (GET /invoices/{number}); wystawianie, walidacja i wysyłka odbywają się w produkcie, a webhook invoice.issued zgłasza wystawienie. Nie ma punktu końcowego, który przyjmuje surowy UBL, wyszukuje uczestnika lub zwraca MLR. Co API może, a czego nie może w zakresie Peppol, opisano na stronie integracja Peppol; szerszy kontekst na stronie Peppol i na stronie wysyłanie i odbieranie, a belgijski obowiązek w hubie Belgia i na stronie kraju.