VPD schéma: dotazy a datový model party

GraphQL dotazy, datový model party a příklady. V souladu s oficiální referencí schématu PSB.

Služba VPD nabízí GraphQL endpoint. Úplná aktuální definice všech dotazů a typů je v oficiální Schema Reference (partySchema) na dokumentačním webu PSB. V GraphQL žádejte jen pole, která potřebujete. Níže uvedený výklad a příklady jsou praktické shrnutí.

Dostupné root dotazy
DotazÚčelpartyVyhledávání stran; výsledky seřazené podle relevancefindBest-effort shoda, když jsou údaje nejisté nebo neúplné (všechny argumenty volitelné)companyKódy právní formy / typu podniku pro danou zemisbiKódy SBI (nizozemská klasifikace odvětví)naceKódy NACE (klasifikace EU)

Podrobnosti a typy pro find, company, sbi a nace jsou v referenci schématu.

Dotaz party: parametry
ParametrTypPopissearchStringVolné hledání přes všechna poleidStringHledání podle identifikátoru (např. obchodní rejstřík, DIČ nebo eConnectId)nameStringHledání podle názvu (firmy)postcodeStringFiltr na PSČcityStringFiltr na místocountryStringKód země, např. NL nebo BElangStringJazyk výsledků; výchozí nlmaxResultsIntMaximální počet výsledků; výchozí 10

Parametry lze kombinovat a hledání zúžit.

Typ party (hlavní pole)
PoleTypPopisidStringeConnect ID stranytypeStringTyp stranyisActiveBooleanZda je strana aktivnípreferredNameStringPrávní název, je-li k dispozici; jinak první obchodní názevlegalNameStringPotvrzený právní název (může být prázdný, pokud není jistě stanoven)tradeNamesStringObchodní názvydescriptionStringKrátký popis činnostíidentifierspartyIdentifierIdentifikátory (rejstřík, DPH, GLN atd.)sectorCodesactivityKódy odvětví (např. SBI/NACE)locationslocationZnámá sídla / adresywebsiteStringWebeDeliveryeDeliveryMožnosti elektronického doručení (včetně kanálů Peppol)highlightshighlightZvýrazněné fragmenty u výsledků hledání
identifiers: partyIdentifier a partyId

Identifikátory už nejsou ploché páry type/value na objektu party. Používá se identifiers: každá položka má name (popisek ze schématu, např. "KvK") a id typu partyId s poli mimo jiné value, text, schemeIdText, schemeIdNumber a schemeAuthority. Všechna pole jsou v referenci schématu.

Lokace

location obsahuje mimo jiné text (úplně formátovanou adresu), street, number, numberAddition, postcode, city, country (objekt mimo jiné s iso) a volitelně latitude / longitude.

Pole eDelivery

Pole eDelivery uvádí podle kanálu, které typy dokumentů může strana přijímat nebo odesílat, bez samostatného SMP lookupu:

PodpolePopisacceptsSeznam typů dokumentů, které strana může přijímatprovidesSeznam typů dokumentů, které strana může odesílat

U každého typu dokumentu se vrací mimo jiné channel (například Peppol), partyId (identifikátor na daném kanálu), listedName, documentName, documentTypeId, processId, family a kanálové details. Integrace tak v jednom volání ověří, zda příjemce přijímá konkrétní typ dokumentu na daném kanálu.

Příklady dotazů
Organizace podle názvu
{
  party(name: "eConnect", country: "NL", maxResults: 5) {
    id
    preferredName
    legalName
    tradeNames
    identifiers {
      name
      id {
        value
        text
        schemeIdText
      }
    }
  }
}
Hledání podle identifikátoru
{
  party(id: "12345678", maxResults: 1) {
    id
    preferredName
    legalName
    locations {
      text
      street
      postcode
      city
      country {
        iso
      }
      latitude
      longitude
    }
    website
  }
}
Volné hledání s více detaily
{
  party(search: "facturatie Woerden", maxResults: 10) {
    id
    type
    isActive
    preferredName
    legalName
    description
    identifiers {
      name
      id {
        value
        text
      }
    }
    sectorCodes {
      type
      value
      text
      description
    }
    locations {
      text
      postcode
      city
      country {
        iso
      }
    }
    website
  }
}
Nejistý vstup: find

Pro fuzzy nebo neúplné údaje použijte find s objektem args (viz dokumentace pro všechna volitelná pole, včetně ids.legal, ids.vat, ids.iban, ids.oin, ids.gln).

{
  find(args: { name: "Gemeente", country: "NL", postcode: "3511" }) {
    eConnectId
    name
    address
    identifiers {
      name
      id {
        value
        text
      }
    }
  }
}
Tipy pro efektivní vyhledávání

Použijte search pro široké textové hledání a name nebo id pro přesnější filtry. Parametrem lang nastavíte jazyk textových polí (výchozí nizozemština). Při testování omezte výsledek pomocí maxResults. U syntaktických nebo schématových chyb zkontrolujte errors v odpovědi GraphQL. Prázdný seznam u party nebo find znamená žádný výsledek, ne nutně chybu.

Časté otázky
Mohu v jednom dotazu `party` kombinovat více parametrů hledání?

Ano. Můžete například použít name spolu s city, postcode nebo country a výsledky zúžit. Oficiální seznam parametrů je v referenci schématu.

Jak si vyžádám identifikátory?

Přes pole identifiers na party. Vyberte name a požadovaná pole id (např. value a text). Nahrazuje to starší vzor s plochým seznamem partyIds { type value }.

Jaký je maximální počet výsledků na dotaz?

Výchozí maximum je 10 výsledků pro party, pokud nenastavíte vyšší maxResults. Pro rychlé ověření často stačí maxResults: 1.


Chcete testovat dotazy interaktivně? Použijte VPD Playground. Nebo si přečtěte, jak VPD zabudujete do své integrace.

Vyzkoušejte VPD Playground