Schema VPD | eConnect

VPD zwraca dane podmiotów jako obiekt party. Ten artykuł opisuje strukturę tego obiektu, dostępne parametry wyszukiwania i przykładowe zapytania, które można bezpośrednio wykorzystać.

Obiekt party

Każdy wynik z VPD ma tę samą strukturę. Poniżej wszystkie pola obiektu party:

Pole

Typ

Opis

id

String

Unikalny identyfikator party w VPD

type

String

Typ organizacji (np. forma prawna)

partyIds

Array

Lista identyfikatorów (KvK, OIN, NIP, GLN itp.)

legalName

String

Oficjalna nazwa prawna

tradeNames

Array

Nazwy handlowe, pod którymi organizacja działa

sectorCodes

Array

Kody SBI lub podobne klasyfikacje sektorowe

locations

Array

Adresy siedzib z danymi adresowymi i współrzędnymi (szerokość/długość geograficzna)

website

String

Strona internetowa organizacji (jeśli znana)

partyIds

Pole partyIds zawiera listę obiektów identyfikatorów. Każdy identyfikator ma type (schemat, np. KVK, OIN, VAT) i value (sam numer). Organizacja może mieć wiele identyfikatorów.

locations

Lokalizacje zawierają dane adresowe (ulica, kod pocztowy, miasto, kraj) i opcjonalnie współrzędne geograficzne (latitude i longitude). Organizacja może mieć wiele siedzib.

Parametry wyszukiwania

VPD przeszukuje się za pomocą następujących parametrów zapytania:

Parametr

Typ

Opis

id

String

Wyszukiwanie po konkretnym identyfikatorze (np. numer KvK)

name

String

Wyszukiwanie po nazwie firmy (prawnej lub handlowej)

postcode

String

Filtrowanie po kodzie pocztowym

city

String

Filtrowanie po mieście

country

String

Filtrowanie po kodzie kraju (ISO 3166-1 alpha-2)

search

String

Wolne wyszukiwanie po wszystkich polach

maxResults

Int

Maksymalna liczba wyników (domyślnie: 10)

Parametry można łączyć, aby zawęzić wyszukiwanie, np. nazwę i miasto jednocześnie.

Przykładowe zapytania

Wyszukiwanie organizacji po nazwie

{
  parties(name: "eConnect", country: "NL", maxResults: 5) {
    id
    legalName
    tradeNames
    partyIds {
      type
      value
    }
  }
}

Wyszukiwanie po identyfikatorze (numer KvK)

{
  parties(id: "12345678", maxResults: 1) {
    id
    legalName
    locations {
      street
      postcode
      city
      country
      latitude
      longitude
    }
    website
  }
}

Wolne wyszukiwanie ze wszystkimi szczegółami

{
  parties(search: "facturatie Woerden", maxResults: 10) {
    id
    type
    legalName
    tradeNames
    partyIds {
      type
      value
    }
    sectorCodes
    locations {
      street
      postcode
      city
      country
    }
    website
  }
}

Wskazówki dotyczące efektywnego wyszukiwania

Przy wyszukiwaniu przez VPD warto wiedzieć, że parametr search przeszukuje wszystkie pola, podczas gdy name i id są bardziej ukierunkowane. Należy używać name, gdy zna się nazwę firmy (lub jej część), a id, gdy dysponuje się dokładnym identyfikatorem. Łączenie postcode lub city z name jest przydatne, gdy oczekuje się wielu wyników i chce się filtrować po lokalizacji.

Należy pamiętać, że maxResults domyślnie wynosi 10. Aby uzyskać więcej wyników, należy podać wyższą wartość. Do szybkiej weryfikacji, czy konkretna organizacja istnieje, wystarczy maxResults: 1 z dokładnym identyfikatorem.

Chcą Państwo testować zapytania interaktywnie? Należy użyć VPD Playground. Lub przeczytać, jak wykorzystać VPD w integracji.

Wypróbuj VPD Playground

Powiązane