Integracja Validated Party Data w aplikacji: uwierzytelnianie, zapytania i przetwarzanie.
Ten artykuł opisuje, jak zintegrować usługę Validated Party Data (VPD) w swojej aplikacji. Od konfiguracji uwierzytelniania po przetwarzanie wyników wyszukiwania: wszystkie kroki do programistycznego odpytywania i weryfikacji danych podmiotów.
Token dostępowy żąda się od identity server eConnect za pomocą przepływu Client Credentials. Należy użyć 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
Token jest ważny przez 3600 sekund. Należy go przechowywać i odnawiać przed wygaśnięciem. Do testów należy używać środowiska akceptacyjnego: accp-identity.econnect.eu.
Należy wysłać żądanie POST do endpointu VPD z zapytaniem w body:
POST https://vpd.econnect.eu/graphql/v1
Authorization: Bearer {jouw-access-token}
Content-Type: application/json
{
"query": "{ parties(name: \"Gemeente Utrecht\", maxResults: 5) { legalName partyIds { type value } locations { city } } }"
}
VPD zwraca odpowiedź JSON z obiektem data zawierającym znalezione podmioty.
Typowa odpowiedź wygląda następująco:
{
"data": {
"parties": [
{
"legalName": "Gemeente Utrecht",
"partyIds": [
{ "type": "KVK", "value": "30280", },
{ "type": "OIN", "value": "00000001002306608000" }
],
"locations": [
{ "city": "Utrecht" }
]
}
]
}
}
Należy iterować po tablicy parties, aby przetworzyć wyniki. Każdy obiekt party zawiera pola żądane w zapytaniu.
Przed wysłaniem faktury można użyć VPD do sprawdzenia, czy odbiorca istnieje i ma prawidłowe identyfikatory. Należy wyszukać po numerze KvK lub nazwie firmy i porównać wynik z danymi we własnym systemie. W ten sposób unika się wysyłania faktur na niewłaściwy adres lub do nieistniejącej organizacji.
Przy tworzeniu nowej relacji w systemie można odpytać VPD, aby automatycznie uzupełnić adres siedziby, nazwy handlowe i sektor. Przyspiesza to onboarding i podnosi jakość danych.
Do wysłania faktury przez Peppol potrzebny jest prawidłowy schemeID i identyfikator. VPD zwraca wszystkie znane identyfikatory organizacji (KvK, OIN, NIP, GLN), dzięki czemu można wybrać właściwy adres routingowy.
Jeśli zapytanie nie daje wyników, VPD zwraca pustą tablicę parties. Przy nieprawidłowych zapytaniach API zwraca tablicę errors z opisem problemu. Należy zawsze sprawdzać, czy odpowiedź zawiera pole errors, zanim przetworzy się data.
W przypadku błędów uwierzytelniania (wygasły lub nieprawidłowy token) API zwraca HTTP 401. Należy wówczas odnowić token dostępowy i spróbować ponownie.
accp-identity.econnect.euidentity.econnect.euaccp-vpd.econnect.eu/graphql/v1vpd.econnect.eu/graphql/v1accp-vpd.econnect.euvpd.econnect.euIntegrację należy zawsze testować najpierw w środowisku akceptacyjnym. Dane w akceptacji mogą różnić się od produkcji.
Potrzebna pomoc przy konfiguracji integracji VPD? Kontakt z TechSupport lub dokumentacja API na psb.econnect.eu.
Wypróbuj VPD Playground