Peppol lookup | eConnect

Před odesláním faktury nebo objednávky chcete vědět, zda je příjemce dostupný. Pomocí endpointu queryRecipientParty jedním voláním ověříte, zda je organizace registrována v síti Peppol, jaké typy dokumentů přijímá a jakým kanálem PSB dokument doručí. Tím předejdete chybám doručení a umožníte vašim uživatelům přímou zpětnou vazbu.

Jak to funguje

PSB automaticky provádí SML/SMP lookup při každém doručení, aby našel správný Access Point příjemce. Pomocí queryRecipientParty můžete tento samý lookup provést předem, aniž byste skutečně odesílali dokument.

API kontroluje:

Zda je příjemce registrován v síti Peppol (SMP registrace)
Jaké typy dokumentů příjemce může přijmout (capabilities)
Přes jaký Access Point je doručení směrováno
Jaký kanál PSB použije (Peppol, DICO, email fallback atd.)

Endpoint

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

Nahraďte {schemeID} identifikačním schématem a {id} číslem příjemce. Použijte jeden z běžných Peppol identifikátorů:

SchemeID

Typ

Příklad

0106

Nizozemské číslo KVK

0106:12345678

0190

Nizozemský OIN (vláda, 20 číslic)

0190:00000001234567890000

9944

Nizozemské číslo DPH

9944:NL123456789B01

0208

Belgické číslo podniku

0208:0123456789

0088

GLN (mezinárodní)

0088:1234567890123

Příklad požadavku

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

Odpověď při úspěchu

Pokud je příjemce dostupný, API vrátí doporučený identifikátor a kanál, který PSB použije:

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

Pole

Popis

id

Peppol identifikátor k použití jako endpointId ve faktuře nebo objednávce

channel

Doručovací kanál, který PSB použije (např. peppol, dico)

description

Popis vybraného kanálu

Použijte hodnotu z id jako EndpointID ve vašem UBL dokumentu.

Odpověď pro neznámého příjemce

Pokud příjemce nebyl nalezen v Peppol, API vrátí 404 s chybovou zprá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á organizace více identifikátorů (KVK, DPH, OIN)? Zkuste jiný schemeID. Ne všichni příjemci jsou registrováni pod každým identifikátorem. Například: organizace je registrována jako 0106:12345678 (KVK), ale ne jako 0088:5412345678908 (GLN). Dostáváte 404? Vždy zkuste číslo KVK (0106) nebo číslo DPH (9944) jako alternativu, nebo použijte POST variantu pro kontrolu více identifikátorů najednou.

POST varianta s více identifikátory

Pokud chcete zkontrolovat více identifikátorů současně, použijte POST variantu. PSB vyhodnotí všechny identifikátory a vrátí nejlepší možnost:

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

{partyId} v URL je vaše vlastní (odesílající) partyId. V těle požadavku uveďte pole možných identifikátorů příjemce:

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

To je užitečné, když nevíte, pod jakým identifikátorem je příjemce registrován. API automaticky vybere nejlepší shodu.

Volitelné parametry

Parametr

Popis

?preferredDocumentTypeId

Dává přednost konkrétnímu formátu dokumentu v lookupu

?includeOptions

Vrací všechny dostupné kanály, nejen doporučený

Odpověď s includeOptions

S ?includeOptions=true odpověď obsahuje pole options se všemi dostupnými doručovacími kanály:

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

Kdy použít?

Použijte queryRecipientParty jako pre-flight check v následujících situacích:

Před odesláním: ověřte, zda je příjemce dostupný před voláním endpointu pro odeslání, abyste mohli poskytnout koncovým uživatelům přímou zpětnou vazbu
Onboarding obchodních vztahů: ověřte při zakládání nového zákazníka nebo dodavatele, zda je již registrován v Peppol
Multi-channel routing: podívejte se, jaký doručovací kanál PSB vybere (Peppol, DICO, email), a volitelně vynuťte alternativní kanál pomocí parametru ?channel při odesílání
Self-billing: ověřte, zda má dodavatel capability pro self-billing, před odesláním self-billing faktury

Poznámka: lookup kontroluje registraci v okamžiku volání. Mezi lookupem a skutečným doručením se registrace může změnit. V praxi je to vzácné, ale mějte to na paměti u velkých dávek s prodlevou mezi kontrolou a doručením.

Tip: Chcete ručně zkontrolovat SMP registraci mimo API? OpenPeppol nabízí Peppol Lookup Service, kde můžete přímo dotazovat SMP a Business Card data účastníka Peppol. Užitečné pro ověření, zda je registrace správně nakonfigurována.

Běžné chyby

Chyba

Příčina

Řešení

API404 "PartyId not found in Peppol"

Příjemce není registrován pro tento typ identifikátoru

Zkuste jiný schemeID (KVK, DPH, OIN)

API404 "No valid delivery options"

Není dostupná žádná trasa k příjemci

Ověřte, zda je příjemce připojen k aktivnímu Peppol service providerovi

Chcete také vidět, jaký Access Point a jaké formáty dokumentů příjemce přesně podporuje? Endpoint Peppol delivery options poskytuje podrobnější přehled SMP registrace.

Vyzkoušet lookup v API

Související