MGBI dostarcza kompleksowe API do pobierania danych z rejestrów i ewidencji publicznych, w tym z Wykazu Podatników VAT (Białej Listy). Listę źródeł danych dostępnych w tej usłudze znajdziesz na stronie:
Ten poradnik dotyczy API dla Wykazu Podatników VAT (Białej Listy), który udostępniamy w ramach produktu:
👉 Wykaz Podatników VAT API (Biała Lista API)
Poniżej opisaliśmy, w jaki sposób możesz pobrać przez API aktualny status podmiotu z Wykazu Podatników VAT na podstawie jego numeru NIP.
Krok 1: Uzyskaj klucz autoryzacji w API
Aby zdobyć klucz autoryzacji wymagany przy wywoływaniu endpointów dostępnych w MGBI API, skontaktuj się z nami przy użyciu formularza kontaktowego na stronie produktu:
👉 Wykaz Podatników VAT API (Biała Lista API)
Krok 2: Wywołaj endpoint Create Refresh
Dane dostępne w Wykazie Podatników VAT udostępniamy w MGBI API w modelu danych o identyfikatorze pl-wpv-record.
Model ten jest synchronizowany na żądanie, co oznacza, że nie dysponujemy dla niego w naszych zbiorach pełną kopią danych dostępnych w rejestrze źródłowym.
Aby uzyskać z modelu aktualne dane dotyczące wskazanego dłużnika, musisz najpierw utworzyć zlecenie ich pobrania z Wykazu Podatników VAT przy użyciu endpointu Create Refresh.
Przykład wywołania endpointu Create Refresh z numerem NIP:
POST /v1/refresh HTTP/1.1
Host: api.mgbi.pl
Authorization: [klucz autoryzacji]
{
"model": "pl-wpv-record",
"pl_nip": [numer NIP]
}
Prawidłowe wywołanie endpointu Create Refresh zwraca w odpowiedzi słownik zawierający identyfikator zlecenia w polu id.
Krok 3: Wywołaj endpoint Get Refresh
Zlecenia pobrania danych z rejestru źródłowego zwykle trwają od kilku do kilkunastu sekund od momentu ich utworzenia endpointem Create Refresh.
Aby sprawdzić aktualny status zlecenia, wywołaj endpoint Get Refresh podając w adresie URL jego identyfikator uzyskany w poprzednim kroku.
Przykład wywołania endpointu Get Refresh z identyfikatorem zlecenia:
GET /v1/refresh/[identyfikator zlecenia] HTTP/1.1
Host: api.mgbi.pl
Authorization: [klucz autoryzacji]
Jeśli w zwróconym słowniku pole status przyjmuje wartość pending, zlecenie jest jeszcze w trakcie wykonywania i należy ponownie wywołać endpoint Get Refresh za kilka sekund.
Jeśli pole status przyjmuje wartość success, to oznacza, że zlecenie zostało wykonane i dane dotyczące wskazanego dłużnika zostały już pobrane z rejestru źródłowego.
Krok 4: Wywołaj endpoint Get Records
API dla modelu pl-wpv-record udostępnia endpoint Get Records, który zwraca rekordy z pełną treścią odpowiedzi z Wykazu Podatników VAT dla wskazanego dłużnika.
👉 Dokumentacja endpointu Get Records dla modelu pl-wpv-record
Aby otrzymać dane pobrane z rejestru źródłowego w utworzonym wcześniej zleceniu, wywołaj endpoint Get Records przekazując identyfikator zlecenia w parametrze refresh_id.
Przykład wywołania endpointu Get Records z identyfikatorem zlecenia:
GET /v1/models/pl-wpv-record/records?refresh_id=[identyfikator zlecenia] HTTP/1.1
Host: api.mgbi.pl
Authorization: [klucz autoryzacji]
Krok 5: Odczytaj z odpowiedzi aktualny status podatnika VAT
Prawidłowe wywołanie endpointu Get Records zwraca w odpowiedzi listę rekordów spełniających podane kryteria.
W powyższym przykładzie endpoint powinien zwrócić listę wyników zawierającą jeden rekord:
{
"count": 1,
"pages": 1,
"results": [
{
"id": [identyfikator rekordu],
"identifiers": [identyfikatory podmiotu],
"version": [informacje o wersji rekordu],
"content": [treść odpowiedzi z wyszukiwarki],
"meta": [metadane rekordu]
}
]
}
Wszystkie dane dostępne w wyszukiwarce Wykazu Podatników VAT dla wskazanego podmiotu możesz znaleźć w słowniku content.subject.
Przykładowa zawartość słownika content.subject:
{
"name": [nazwa podmiotu],
"nip": [numer NIP],
"statusVat": [status podatnika VAT],
"regon": [numer REGON],
"krs": [numer KRS],
"workingAddress": [adres siedziby],
"representatives": [dane reprezentantów],
"authorizedClerks": [dane pełnomocników],
"partners": [dane wspólników],
"registrationLegalDate": [data rejestracji podanika VAT],
"accountNumbers": [lista numerów rachunków bankowych],
"hasVirtualAccounts": [informacja, czy podatnik posiada rachunki wirtualne]
}
Aktualny status podatnika VAT dla wskazanego podmiotu możesz odczytać z pola content.subject.statusVat.
Uzyskaj więcej informacji:
