PSB jest certyfikowanym Peppol Access Point i SMP (Service Metadata Publisher). Za pośrednictwem API konfiguruje się typy dokumentów, które organizacja może odbierać, publikuje dane firmy w Peppol Directory i zarządza rejestracją SMP. Ten artykuł omawia tło techniczne i endpointy API, które się do tego wykorzystuje.

Peppol działa w modelu 4-corner: nadawca (C1) wysyła za pośrednictwem swojego Access Point (C2) dokument do Access Point odbiorcy (C3), który przekazuje go do odbiorcy (C4). Routing opiera się na dwóch centralnych komponentach:

• SML (Service Metadata Locator): centralny rejestr DNS, który wskazuje na właściwy SMP odbiorcy
• SMP (Service Metadata Publisher): zawiera metadane odbiorcy, jakie dokumenty może odbierać i za pośrednictwem jakiego Access Point

Gdy wysyła się fakturę przez PSB, PSB automatycznie wykonuje lookup SML/SMP, aby znaleźć właściwy Access Point odbiorcy. Jako integrator nie trzeba tego robić samodzielnie.

Infrastruktura Peppol jest aktywnie rozwijana. Dla integratorów korzystających z API PSB nie ma to wpływu: PSB obsługuje lookupy SML/SMP automatycznie. Poniżej aktualne zmiany do wiadomości.

Insourcing SML. OpenPeppol przejmuje zarządzanie SML od Komisji Europejskiej (DG DIGIT). Okno migracji zostało otwarte 19 marca 2026. Obowiązują dwa oddzielne terminy: termin rejestracji SMP to 31 maja 2026, okres migracji dla AP Lookup (rozwiązywanie DNS) został wydłużony do 31 sierpnia 2026. OpenPeppol dyskutuje z Komisją Europejską, czy termin rejestracji SMP również może zostać wydłużony. Dla integratorów API nic się nie zmienia w endpointach ani lookupach: PSB obsługuje migrację wewnętrznie.

Migracja CNAME do NAPTR. Migracja rekordów DNS CNAME na rekordy NAPTR dla lookupów SML została zakończona w marcu 2026. NAPTR jest obowiązkowy od 1 lutego 2026. Stare rekordy CNAME zostały usunięte z sieci testowej SMK (4 marca 2026) i sieci produkcyjnej SML (11 marca 2026). Jest to wewnętrzna zmiana DNS w infrastrukturze Peppol. PSB już używa NAPTR i nie są potrzebne żadne dostosowania w integracji.

Migracja PKI G3. OpenPeppol przygotowuje przejście z certyfikatów PKI Generation 2 (G2) na Generation 3 (G3). Certyfikaty G3 są używane do wzajemnej komunikacji między Access Points. Peppol Testbed obsługuje zarówno certyfikaty G2, jak i G3 od marca 2026, aby Service Providers mogli testować z wyprzedzeniem. Nie opublikowano jeszcze obowiązkowej daty przejścia. Dla integratorów API nic się nie zmienia: PSB obsługuje odnowienie certyfikatów wewnętrznie.

Peppol obsługuje logistyczne typy dokumentów oprócz faktur za pośrednictwem specyfikacji Peppol Logistics. Wersja 1.2 jest obowiązkowa od 16 marca 2026. Wersja 1.3 jest obowiązkowa od 24 sierpnia 2026.

Obsługiwane dokumenty logistyczne:

• Despatch Advice (list przewozowy)
• Weight Statement
• Transport Execution Plan
• Waybill

Nowe funkcje w wersji 1.3:

• ProductTraceID ze schemeID dla ItemInstance
• DespatchAdviceTypeCode rozszerzony o wartości do identyfikacji przypadków użycia (101, 102, 112, 203-211, 303-311)
• DocumentStatusCode z nową wartością "55 - Notification only" dla zmian po fakturowaniu
• Waste Declaration Number jako AdditionalItemProperty
• Nowa lista kodów ProductTraceIDschemeIDCode

Wersja 1.3 rozwiązuje RFC LLC-27 do LLC-35, w tym wyrównanie ItemInstance, aktualizacje niefakturowe i kody podtraktowania dla odpadów.

Podczas rejestracji party w SMP eConnect, za pomocą capability określa się, jakie typy dokumentów ta party może odbierać. Każda capability ma trzy możliwe stany:

Zalecana wartość dla nowych rejestracji to inherited, chyba że party musi konkretnie odbiegać od standardu.

Capability konfiguruje się za pośrednictwem endpointu Peppol config:

PUT /api/v1/peppol/config/party/{partyId}

W body żądania określa się pożądany stan dla każdej capability. Przykład:

{
  "capabilities": {
    "invoices": "on",
    "selfbilling": "inherited",
    "invoiceResponse": "on",
    "orderOnly": "on",
    "orderAdvanced": "off"
  }
}

Peppol Directory jest publicznym rejestrem wszystkich uczestników Peppol. Publikując businessCard, party staje się wyszukiwalna w directory. BusinessCard zawiera:

BusinessCard jest publikowana za pośrednictwem endpointu Enrollment lub konfiguracji SMP. Po publikacji organizacja jest wyszukiwalna na directory.peppol.eu.

API PSB nie wyprowadza żadnych pól z powiązanego rejestru handlowego. Niezależnie od schematu identyfikatora (KvK 0106, VAT 9944, OIN 0190, GLN 0088 lub innego), zarówno names, jak i address z kodem kraju muszą być jawnie obecne w payload. Przykład poprawnie skonfigurowanej businessCard:

"businessCard": {
  "names": {
    "value": "eVerbinding, eConnect",
    "state": "on",
    "description": "Business names."
  },
  "address": {
    "value": "Pelmolenlaan 16A, 3447 GW, Woerden, NL",
    "state": "on",
    "description": "Geographic information."
  },
  "emailAddress": {
    "value": "techsupport@econnect.eu",
    "state": "on",
    "description": "Technical contact"
  },
  "state": "on"
}

Kod kraju (w powyższym przykładzie NL na końcu pola address) musi być jawnie podany.

Ten komunikat błędu jest diagnostycznie jednoznaczny: przesłany payload nie zawiera names albo pole address nie zawiera kodu kraju. Rozwiązaniem jest zawsze jawne uzupełnienie tych pól w payload businessCard, a nie zmiana na innym poziomie (party, identyfikator, capabilities SMP). Komunikat pojawia się w praktyce stosunkowo często przy integracji GLN (0088), ponieważ partnerzy integracji GLN rzadziej korzystają z szablonu, który standardowo przesyła te pola. PSB nie wykazuje innego zachowania dla GLN niż dla pozostałych schematów.

Wstępne sprawdzenie, czy odbiorca jest osiągalny w Peppol, odbywa się według typu dokumentu i przez zaawansowany endpoint lookup:

Odpowiedź pokazuje dostępne kanały, wybrany Access Point i obsługiwane typy dokumentów. Tych endpointów należy używać do walidacji z wyprzedzeniem, czy dostarczenie się powiedzie. Są dostępne bez ograniczeń we wszystkich pakietach (proaktywne wykrywanie/discovery tras).

Uwaga: w przypadku niezgodności SML/SMP na endpoincie deliveryOption wywołanie nie kończy się błędem natychmiast. W środowisku produkcyjnym nie ma obsługi fail-fast: wywołanie jest kontynuowane i zwraca timeout dopiero po około 30 sekundach. Należy to uwzględnić w obsłudze błędów integracji.

W sieci Peppol jeden participantId w SML wskazuje jedną SMP. Za pomocą rekordu Redirect w SMP można dla konkretnych kombinacji typu dokumentu i identyfikatora procesu wskazać wtórną SMP. Peppol obsługuje tylko jeden poziom przekierowania: cel przekierowania nie może sam zawierać przekierowania.

Alternatywne źródła lookupów SMP: peppolautoriteit.nl/discover (NPa), peppol.helger.com i directory.peppol.eu (niepełne).

Każda party w SMP jest identyfikowana za pomocą identyfikatora ze schemeID. Najczęściej używane schematy:

API PSB akceptuje zarówno numeryczny schemeID, jak i kod literowy: 9925:BE0835689642 jest równoważne z BE:VAT:BE0835689642. Przy korzystaniu z zewnętrznych narzędzi wyszukiwania (takich jak SMP lookup) należy używać oficjalnych numerycznych schemeID.

Party może mieć wiele identyfikatorów, ale każda faktura może zawierać tylko jeden EndpointID.

W Belgii do Peppol używane są dwa typy identyfikatorów. Numer przedsiębiorstwa (KBO, schemeID 0208) jest głównym numerem identyfikacyjnym i obowiązkowym dla odbioru Peppol. Rejestracja na numer VAT (schemeID 9925) jest opcjonalna, dlatego wyszukiwanie belgijskiej organizacji po numerze przedsiębiorstwa kończy się sukcesem częściej niż po numerze VAT.

Numer przedsiębiorstwa można wyprowadzić z numeru VAT, usuwając prefiks kodu kraju (BE). Na przykład: numer VAT BE0835689642 odpowiada numerowi przedsiębiorstwa 0835689642.

Podczas wysyłania dokumentu PSB wyodrębnia identyfikator Peppol z elementu EndpointID w XML. Ten element określa, do jakiego odbiorcy dokument jest kierowany. Jeśli EndpointID jest nieobecny lub nieprawidłowo wypełniony, dokument nie jest prawidłowy i otrzymuje status InvoiceSentError.

Nieprawidłowy XML nie jest automatycznie ponawiany. Korekta leży po stronie systemu źródłowego (pakietu oprogramowania generującego fakturę), a nie PSB. Należy z wyprzedzeniem sprawdzić za pomocą queryRecipientParty, czy odbiorca jest osiągalny w sieci Peppol.

Reguła walidacji NLCIUS wymagająca, aby schemeID elementu CompanyID miało wartość 0190 (OIN), gdy odbiorcą jest podmiot publiczny. Na platformie identyfikator organizacji i "Wyślij przez" muszą używać tego samego typu identyfikatora. Rozbieżność skutkuje błędem walidacji dokumentu.

Gdy dostawca zgłasza, że faktura została dostarczona do eConnect jako Access Point, a odbiorca twierdzi, że nic nie otrzymał, diagnoza po stronie odbiorcy przebiega przez returnedMessageId.

returnedMessageId to identyfikator tworzony przez eConnect w momencie, gdy Access Point akceptuje lub odrzuca dokument na poziomie AS4. Zwykle ma postać GUID@econnect.eu. Za pomocą tego identyfikatora Support może odnaleźć fakturę w systemie i prześledzić ścieżkę przetwarzania.

Najczęstsze przyczyny, dla których dokument jest uznany za "dostarczony" przez wysyłający AP, ale nie dociera do odbiorcy:

• Nieprawidłowy dokument: dokument jest odrzucany na poziomie AS4 przez odbierający AP. Wysyłający AP otrzymuje komunikat o błędzie.
• Naruszenie Enveloping Compliance: nadawca i odbiorca w dokumencie nie zgadzają się z nadawcą i odbiorcą na kopercie (SBDH). Taka rozbieżność prowadzi do odrzucenia.

Ścieżka wsparcia: za pomocą returnedMessageId Support odnajduje niemal wszystkie dokumenty przez Management API. Jeśli wyszukanie się nie powiedzie, Support angażuje TechSupport.

Chcą Państwo zautomatyzować cały proces rejestracji? Proszę przeczytać artykuł o Enrollment API, który pozwala skonfigurować rejestrację, capability i hooki w jednym wywołaniu API.

• Rejestracja Peppol przez API (Enrollment)
• Migracja do lub z eConnect
• Konfiguracja dostarczenia multi-channel
• Przegląd: Procurement Service Bus (PSB)
• Czym jest Peppol i jak działa sieć?
• Rejestracja w Peppol (platforma)