Peppol lookup | eConnect

Przed wysłaniem faktury lub zamówienia chcesz wiedzieć, czy odbiorca jest osiągalny. Za pomocą endpointu queryRecipientParty w jednym wywołaniu sprawdzasz, czy organizacja jest zarejestrowana w sieci Peppol, jakie typy dokumentów są akceptowane i przez jaki kanał PSB dostarczy dokument. Zapobiega to błędom dostarczania i pozwala przekazać użytkownikom bezpośrednią informację zwrotną.

Jak to działa

PSB automatycznie wykonuje wyszukiwanie SML/SMP przy każdym dostarczeniu, aby znaleźć właściwy Access Point odbiorcy. Za pomocą queryRecipientParty możesz wykonać to samo wyszukiwanie z wyprzedzeniem, bez faktycznego wysyłania dokumentu.

API sprawdza:

Czy odbiorca jest zarejestrowany w sieci Peppol (rejestracja SMP)
Jakie typy dokumentów odbiorca może przyjąć (capabilities)
Przez jaki Access Point odbywa się dostarczanie
Jaki kanał PSB użyje (Peppol, DICO, email fallback itp.)

Endpoint

GET /api/v1/queryRecipientParty?identifier={schemeID}:{id}

Zastąp {schemeID} schematem identyfikacji, a {id} numerem odbiorcy. Użyj jednego z popularnych identyfikatorów Peppol:

SchemeID

Typ

Przykład

0106

Numer KVK (holenderski)

0106:12345678

0190

Holenderski OIN (instytucje publiczne, 20 cyfr)

0190:00000001234567890000

9944

Numer VAT (holenderski)

9944:NL123456789B01

0208

Belgijski numer przedsiębiorstwa

0208:0123456789

0088

GLN (międzynarodowy)

0088:1234567890123

Przykładowe żądanie

GET /api/v1/queryRecipientParty?identifier=0106:12345678

Odpowiedź w przypadku sukcesu

Jeśli odbiorca jest osiągalny, API zwraca zalecany identyfikator i kanał, którego użyje PSB:

{
  "id": "NL:KVK:12345678",
  "channel": "peppol",
  "description": "default send via peppol delivery"
}

Pole

Opis

id

Identyfikator Peppol do użycia jako endpointId w fakturze lub zamówieniu

channel

Kanał dostarczania, którego użyje PSB (np. peppol, dico)

description

Opis wybranego kanału

Użyj wartości z id jako EndpointID w swoim dokumencie UBL.

Odpowiedź dla nieznanego odbiorcy

Jeśli odbiorca nie został znaleziony w Peppol, API zwraca 404 z komunikatem błędu:

{
  "helpLink": "https://psb.econnect.eu/endpoints/v1/SalesInvoice.html#query-recipient-party",
  "message": "PartyId 'NL:KVK:12345678' not found in Peppol.",
  "code": "API404",
  "requestId": "41cd5529904be94d941137068c1c3fa1",
  "dateTime": "2026-03-14T10:22:19.4878393+00:00"
}

Wskazówka: Czy organizacja ma wiele identyfikatorów (KVK, VAT, OIN)? Spróbuj innego schemeID. Nie wszyscy odbiorcy są zarejestrowani pod każdym identyfikatorem. Na przykład: organizacja jest zarejestrowana jako 0106:12345678 (KVK), ale nie jako 0088:5412345678908 (GLN). Otrzymujesz 404? Zawsze spróbuj numeru KVK (0106) lub numeru VAT (9944) jako alternatywy, lub użyj wariantu POST, aby sprawdzić wiele identyfikatorów na raz.

Wariant POST z wieloma identyfikatorami

Jeśli chcesz sprawdzić wiele identyfikatorów jednocześnie, użyj wariantu POST. PSB ocenia wszystkie identyfikatory i zwraca najlepszą opcję:

POST /api/v1/{partyId}/salesInvoice/queryRecipientParty

{partyId} w URL to Twoje własne (wysyłające) partyId. W treści żądania podaj tablicę możliwych identyfikatorów odbiorcy:

["0106:12345678", "9944:NL123456789B01", "0190:00000001234567890000"]

Jest to przydatne, gdy nie wiesz, pod jakim identyfikatorem odbiorca jest zarejestrowany. API automatycznie wybiera najlepsze dopasowanie.

Opcjonalne parametry

Parametr

Opis

?preferredDocumentTypeId

Nadaje priorytet konkretnemu formatowi dokumentu w wyszukiwaniu

?includeOptions

Zwraca wszystkie dostępne kanały, nie tylko zalecany

Odpowiedź z includeOptions

Z ?includeOptions=true odpowiedź zawiera tablicę options ze wszystkimi dostępnymi kanałami dostarczania:

{
  "id": "NL:KVK:12345678",
  "channel": "peppol",
  "description": "default send via peppol delivery",
  "options": [
    {
      "channel": "peppol",
      "description": "default send via peppol delivery",
      "identifiers": [
        {
          "partyId": {
            "text": "NL:KVK:12345678",
            "value": "12345678",
            "schemeAuthority": "iso6523-actorid-upis",
            "schemeIdText": "NL:KVK",
            "schemeIdNumber": "0106"
          },
          "isValid": true
        }
      ]
    }
  ]
}

Kiedy używać?

Użyj queryRecipientParty jako pre-flight check w następujących sytuacjach:

Przed wysyłką: sprawdź, czy odbiorca jest osiągalny przed wywołaniem endpointu wysyłki, aby móc przekazać użytkownikom bezpośrednią informację zwrotną
Onboarding relacji: zweryfikuj podczas tworzenia nowego klienta lub dostawcy, czy jest już zarejestrowany w Peppol
Multi-channel routing: zobacz, jaki kanał dostarczania PSB wybierze (Peppol, DICO, email) i opcjonalnie wymuś alternatywny kanał za pomocą parametru ?channel podczas wysyłki
Self-billing: sprawdź, czy dostawca posiada capability self-billing, zanim wyślesz fakturę self-billing

Uwaga: wyszukiwanie sprawdza rejestrację w momencie wywołania. Między wyszukiwaniem a faktycznym dostarczeniem rejestracja może się zmienić. W praktyce zdarza się to rzadko, ale miej to na uwadze przy dużych partiach z opóźnieniem między sprawdzeniem a dostarczeniem.

Wskazówka: chcesz ręcznie sprawdzić rejestrację SMP, poza API? OpenPeppol oferuje Peppol Lookup Service, gdzie możesz bezpośrednio odpytać dane SMP i Business Card uczestnika Peppol. Przydatne do weryfikacji, czy rejestracja jest poprawnie skonfigurowana.

Najczęstsze błędy

Błąd

Przyczyna

Rozwiązanie

API404 "PartyId not found in Peppol"

Odbiorca nie jest zarejestrowany dla tego typu identyfikatora

Spróbuj innego schemeID (KVK, VAT, OIN)

API404 "No valid delivery options"

Brak dostępnej trasy do odbiorcy

Sprawdź, czy odbiorca jest podłączony do aktywnego dostawcy usług Peppol

Chcesz też zobaczyć, jaki Access Point i jakie formaty dokumentów dokładnie obsługuje odbiorca? Endpoint Peppol delivery options zapewnia bardziej szczegółowy przegląd rejestracji SMP.

Wypróbuj lookup w API

Powiązane