Validated Party Data integreren in je applicatie: authenticatie, queries en verwerking.
Dit artikel beschrijft hoe je de Validated Party Data (VPD) service inbouwt in je applicatie. Van het opzetten van de authenticatie tot het verwerken van zoekresultaten: alle stappen om partijgegevens programmatisch op te vragen en te verifiëren.
Vraag een access token aan bij de eConnect identity server met de Client Credentials flow. Gebruik scope vpd:
POST https://identity.econnect.eu/connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=jouw-client-id
&client_secret=jouw-client-secret
&scope=vpd
Het token is 3600 seconden geldig. Bewaar het token en vernieuw het voordat het verloopt. Gebruik voor testen de acceptatieomgeving: accp-identity.econnect.eu.
Stuur een POST-request naar het VPD-endpoint met je query in de body:
POST https://vpd.econnect.eu/graphql/v1
Authorization: Bearer {jouw-access-token}
Content-Type: application/json
{
"query": "{ party(name: \"Gemeente Utrecht\", maxResults: 5) { legalName preferredName identifiers { name id { value text } } locations { city } } }"
}
De VPD retourneert een JSON-response met een data-object dat onder de root query (hier: party) een lijst met treffers bevat.
Een typische response ziet er zo uit:
{
"data": {
"party": [
{
"legalName": "Gemeente Utrecht",
"preferredName": "Gemeente Utrecht",
"identifiers": [
{
"name": "KvK",
"id": { "value": "12345678", "text": "12345678" }
},
{
"name": "OIN",
"id": { "value": "00000001002306608000", "text": "00000001002306608000" }
}
],
"locations": [
{ "city": "Utrecht" }
]
}
]
}
}
Loop door de lijst onder party om de resultaten te verwerken. Elk element bevat de velden die je in je query hebt opgevraagd. Het exacte datamodel staat in de VPD schema reference.
Voordat je een factuur verstuurt, kun je de VPD gebruiken om te controleren of de ontvanger bestaat en de juiste identifiers heeft. Zoek op KvK-nummer of bedrijfsnaam en vergelijk het resultaat met de gegevens in je eigen systeem. Zo voorkom je dat facturen naar een verkeerd adres of een niet-bestaande organisatie worden verstuurd.
Wanneer een nieuwe relatie wordt aangemaakt in je systeem, kun je de VPD raadplegen om het vestigingsadres, de handelsnamen en de sector automatisch aan te vullen. Dit versnelt de onboarding en verhoogt de datakwaliteit.
Om een factuur via Peppol te versturen, heb je het juiste schemeID en identifier nodig. De VPD retourneert alle bekende identifiers van een organisatie (KvK, OIN, BTW, GLN), zodat je het juiste routeringsadres kunt selecteren.
Als een query geen resultaten oplevert, retourneert de VPD een lege lijst bij de betreffende root query (bijv. party of find). Bij ongeldige queries retourneert de API een errors-array met een beschrijving van het probleem. Controleer altijd of de response een errors-veld bevat voordat je de data verwerkt.
Bij authenticatiefouten (verlopen of ongeldig token) retourneert de API een HTTP 401. Vernieuw in dat geval je access token en probeer het opnieuw.
accp-identity.econnect.euidentity.econnect.euaccp-vpd.econnect.eu/graphql/v1vpd.econnect.eu/graphql/v1accp-vpd.econnect.euvpd.econnect.euTest je integratie altijd eerst op de acceptatieomgeving. De data in acceptatie kan afwijken van productie.
Hulp nodig bij het opzetten van je VPD-integratie? Neem contact op met TechSupport of bekijk de API-documentatie op psb.econnect.eu.
Probeer de VPD Playground