Konfiguracja capability SMP, Peppol Directory i businessCard za pośrednictwem API PSB.
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:
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 w member review do 15 kwietnia 2026, z przewidywaną publikacją 18 maja 2026.
Obsługiwane dokumenty logistyczne:
Nowe funkcje w wersji 1.3:
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:
onoffinheritedZalecana wartość dla nowych rejestracji to inherited, chyba że party musi konkretnie odbiegać od standardu.
invoicesselfbillinginvoice_bisv2reviewsinvoiceResponseordersorderOnlyorderAdvancedorderResponseorderResponseAdvancedCapability 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.
Both name(s) and country code are required when adding a business cardTen 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:
POST /api/v1/{partyId}/salesInvoice/queryRecipientParty["0106:..."] lub { "partyIds": [...], "metaAttributes": {...} }; opcjonalne ?preferredDocumentTypeId, ?includeOptionsPOST /api/v1/{partyId}/purchaseOrder/queryRecipientParty?documentFamily=OrderGET /api/v1/peppol/deliveryOption?partyIds=...&documentFamily=...&isCredit=...partyId, documentTypeId, processId, protocol (As2/As4), url, certificateOdpowiedź 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
deliveryOptionwywoł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.
Każda party w SMP jest identyfikowana za pomocą identyfikatora ze schemeID. Najczęściej używane schematy:
01060106:1234567801900190:0000000123456789000099449944:NL123456789B010208BE:EN0208:01234567899925BE:VAT9925:BE0835689642 (również BE1xxxxxxxxx jest ważny od 2025)00880088:1234567890123API 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.
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.
Zobacz endpointy SMP