/ docs
ProduktZnalostiVývojári
Platforma Control
Peppol lookup: overenie príjemcu cez API

Vopred overte, či je príjemca dostupný cez Peppol, pomocou endpointu queryRecipientParty.

Pred odoslaním faktúry alebo objednávky chcete vedieť, či je príjemca dostupný. Pomocou endpointu queryRecipientParty jedným volaním overíte, či je organizácia registrovaná v sieti Peppol, aké typy dokumentov prijíma a akým kanálom PSB dokument doručí. Tým predídete chybám doručenia a umožníte vašim používateľom priamu spätnú väzbu.

Ako to funguje

PSB automaticky vykonáva SML/SMP lookup pri každom doručení, aby našiel správny Access Point príjemcu. Pomocou queryRecipientParty môžete tento istý lookup vykonať vopred, bez skutočného odosielania dokumentu.

API kontroluje:

  • Či je príjemca registrovaný v sieti Peppol (SMP registrácia)
  • Aké typy dokumentov príjemca môže prijať (capabilities)
  • Cez aký Access Point je doručenie smerované
  • Aký kanál PSB použije (Peppol, DICO, email fallback atď.)
Endpoint
GET /api/v1/queryRecipientParty?identifier={schemeID}:{id}

Nahraďte {schemeID} identifikačnou schémou a {id} číslom príjemcu. Použite jeden z bežných Peppol identifikátorov:

SchemeIDTypPríklad0106Holandské číslo KVK0106:123456780190Holandský OIN (vláda, 20 číslic)0190:000000012345678900009944Holandské číslo DPH9944:NL123456789B010208Belgické číslo podniku0208:01234567890088GLN (medzinárodný)0088:1234567890123
Príklad požiadavky
GET /api/v1/queryRecipientParty?identifier=0106:12345678
Odpoveď pri úspechu

Ak je príjemca dostupný, API vráti odporúčaný identifikátor a kanál, ktorý PSB použije:

{
  "id": "NL:KVK:12345678",
  "channel": "peppol",
  "description": "default send via peppol delivery"
}
PolePopisidPeppol identifikátor na použitie ako endpointId vo faktúre alebo objednávkechannelDoručovací kanál, ktorý PSB použije (napr. peppol, dico)descriptionPopis vybraného kanálu

Použite hodnotu z id ako EndpointID vo vašom UBL dokumente.

Odpoveď pre neznámeho príjemcu

Ak príjemca nebol nájdený v Peppol, API vráti 404 s chybovou správou:

{
  "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"
}

Tip: Má organizácia viacero identifikátorov (KVK, DPH, OIN)? Skúste iný schemeID. Nie všetci príjemcovia sú registrovaní pod každým identifikátorom. Napríklad: organizácia je registrovaná ako 0106:12345678 (KVK), ale nie ako 0088:5412345678908 (GLN). Dostávate 404? Vždy skúste číslo KVK (0106) alebo číslo DPH (9944) ako alternatívu, alebo použite POST variantu na kontrolu viacerých identifikátorov naraz.

POST varianta s viacerými identifikátormi

Ak chcete skontrolovať viacero identifikátorov súčasne, použite POST variantu. PSB vyhodnotí všetky identifikátory a vráti najlepšiu možnosť:

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

{partyId} v URL je vaše vlastné (odosielajúce) partyId. V tele požiadavky uveďte pole možných identifikátorov príjemcu:

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

To je užitočné, keď neviete, pod akým identifikátorom je príjemca registrovaný. API automaticky vyberie najlepšiu zhodu.

Voliteľné parametre
ParameterPopis?preferredDocumentTypeIdUprednostňuje konkrétny formát dokumentu v lookupe?includeOptionsVracia všetky dostupné kanály, nielen odporúčaný
Odpoveď s includeOptions

S ?includeOptions=true odpoveď obsahuje pole options so všetkými dostupnými doručovacími kanálmi:

{
  "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
        }
      ]
    }
  ]
}
Kedy použiť?

Použite queryRecipientParty ako pre-flight check v nasledovných situáciách:

  • Pred odoslaním: overte, či je príjemca dostupný pred volaním endpointu na odoslanie, aby ste mohli poskytnúť koncovým používateľom priamu spätnú väzbu
  • Onboarding obchodných vzťahov: overte pri zakladaní nového zákazníka alebo dodávateľa, či je už registrovaný v Peppol
  • Multi-channel routing: pozrite sa, aký doručovací kanál PSB vyberie (Peppol, DICO, email), a voliteľne vynúťte alternatívny kanál pomocou parametra ?channel pri odosielaní
  • Self-billing: overte, či má dodávateľ capability pre self-billing, pred odoslaním self-billing faktúry

Poznámka: lookup kontroluje registráciu v okamihu volania. Medzi lookupom a skutočným doručením sa registrácia môže zmeniť. V praxi je to zriedkavé, ale majte to na pamäti pri veľkých dávkach s oneskorením medzi kontrolou a doručením.

Tip: Chcete manuálne skontrolovať SMP registráciu mimo API? OpenPeppol ponúka Peppol Lookup Service, kde môžete priamo dotazovať SMP a Business Card dáta účastníka Peppol. Užitočné na overenie, či je registrácia správne nakonfigurovaná.

Bežné chyby
ChybaPríčinaRiešenieAPI404 "PartyId not found in Peppol"Príjemca nie je registrovaný pre tento typ identifikátoraSkúste iný schemeID (KVK, DPH, OIN)API404 "No valid delivery options"Nie je dostupná žiadna trasa k príjemcoviOverte, či je príjemca pripojený k aktívnemu Peppol service providerovi

Chcete tiež vidieť, aký Access Point a aké formáty dokumentov príjemca presne podporuje? Endpoint Peppol delivery options poskytuje podrobnejší prehľad SMP registrácie.

Vyskúšať lookup v API

Súvisiace
PreviousSieť Peppol
NextRegistrácia Peppol