Dane firmy po NIP przez API: GUS REGON, biała lista VAT, KRS, CEIDG i VIES

Który rejestr odpowiada na które pytanie

Nie ma jednego urzędowego API, które odpowie na wszystko. Są rejestry prowadzone przez różne instytucje, każdy zbudowany do innego celu, więc zacznij od ustalenia, na jakie pytanie ma odpowiadać Twój system.

Typowa potrzeba to uzupełnienie nazwy i adresu firmy, gdy klient wpisze NIP w formularzu, w koszyku albo w CRM-ie. Do tego służy rejestr REGON prowadzony przez Główny Urząd Statystyczny. Według GUS wpisowi do niego podlegają osoby prawne, jednostki organizacyjne niemające osobowości prawnej i osoby fizyczne prowadzące działalność gospodarczą, więc w jednym miejscu znajdziesz i spółkę, i jednoosobową działalność.

Pozostałe rejestry odpowiadają na inne pytania. Biała lista Ministerstwa Finansów mówi, czy firma jest podatnikiem VAT i czy rachunek do niej należy. Otwarte API Krajowego Rejestru Sądowego zwraca odpis spółki. Hurtownia danych CEIDG udostępnia dane jednoosobowych działalności prosto ze źródła, a VIES, system Komisji Europejskiej, potwierdza numer VAT firmy z innego kraju Unii.

W praktyce wybór wygląda tak. Formularz, który ma sam wpisać nazwę i adres każdemu klientowi, łączysz z GUS: zwraca adres rozbity na pola, a limit wynosi od 6000 do 10 000 zapytań na godzinę, zależnie od pory dnia; w zamian potrzebujesz klucza, o który trzeba poprosić, i klienta SOAP. Jeśli potrzebujesz prostego REST-a z JSON-em bez klucza i sprawdzasz kilkadziesiąt firm dziennie, wystarczy metoda search białej listy, która też zwraca nazwę, adres i status VAT. Odpis spółki bierzesz z KRS, a numer VAT klienta z innego kraju sprawdzasz w VIES.

Bywa też, że integracja w ogóle się nie opłaca. Jeśli program do faktur albo platforma sklepu, z których korzystasz, już sam uzupełnia dane kontrahenta, własny kod niczego nie doda. A jeśli zamówień na firmę masz kilka w tygodniu, rozważ, czy ręczne sprawdzenie w publicznej wyszukiwarce REGON nie wystarczy: integracja to klucz, klient SOAP, kolejka pod limity i obsługa przerw, które ktoś musi utrzymywać.

Co oferuje każde z urzędowych źródeł, według instytucji, które je prowadzą

Tabela jest szersza niż ekran: przesuń ją palcem w bok.

Usługa BIR w GUS: klucz, dane i protokół

Usługa BIR, czyli Baza Internetowa REGON, to podstawowe źródło nazwy i adresu firmy, gdy znasz jej NIP. GUS pisze na stronie usługi wprost: „Usługa i dane udostępniane są bezpłatnie”.

Według Biuletynu Informacji Publicznej GUS rejestr przechowuje oprócz nazwy i adresu między innymi formę prawną, przeważającą działalność, daty zawieszenia, wznowienia i zakończenia działalności oraz nazwę i numer rejestru, do którego wpisano podmiot. Statusu VAT w nim nie ma. Według instrukcji technicznej baza usługi synchronizuje się co kilka minut, ale REGON jest rejestrem wtórnym, więc jego aktualność zależy od rejestrów pierwotnych, takich jak CEIDG i KRS.

Do podpowiedzi w formularzu zwykle wystarcza jedno wywołanie DaneSzukajPodmioty po NIP. Według schematu odpowiedzi z dokumentacji GUS zwraca ono REGON, nazwę i adres rozbity na pola, od województwa po numer lokalu, a także typ podmiotu i datę zakończenia działalności. Pełny raport, pobierany po REGON-ie metodą DanePobierzPelnyRaport, jest potrzebny dopiero po formę prawną, kody PKD albo daty zawieszenia. Przy jednoosobowej firmie pole SilosID mówi, czy adres dotyczy działalności z CEIDG, rolniczej czy tak zwanej pozostałej, a jedna osoba może mieć kilka takich adresów pod jednym REGON-em, więc formularz powinien umieć pokazać więcej niż jeden wynik.

Dwie pułapki widać dopiero przy pierwszym wywołaniu. Według instrukcji metody zwracają wynik jako tekst, w którym siedzi dokument XML z listą rekordów, więc odpowiedź SOAP parsujesz dwa razy. Pusta odpowiedź nie mówi z kolei, co się stało: przyczynę podaje metoda GetValue z parametrem KomunikatKod, gdzie 4 oznacza brak podmiotu, a kod 7 albo pusta odpowiedź samej metody GetValue wygasłą sesję, po której wystarczy ponownie wywołać Zaloguj.

BIR to usługa SOAP, a nie REST, co od razu wpływa na wybór biblioteki po stronie serwera. Najważniejsze szczegóły techniczne z dokumentacji GUS zebrałem w tabeli niżej. Klucz do środowiska produkcyjnego dostajesz, pisząc na adres regon_bir@stat.gov.pl; według strony usługi GUS prosi w tej wiadomości o poniższe dane i deklaruje wsparcie techniczne w trakcie integracji.

• Dane podmiotuPełna nazwa i numer REGON firmy, która będzie korzystać z usługi; osoba bez działalności gospodarczej podaje NIP.
• Osoba do kontaktuImię i nazwisko, adres e-mail oraz numer telefonu stacjonarnego albo komórkowego.
• Adresy IPWymagane, gdy użytkownicy łączą się z usługą przez Twój serwer (instrukcja nazywa to zalecaną architekturą). Stały adres GUS radzi podać także na potrzeby diagnostyki.
• Liczba jednoczesnych użytkownikówPrzybliżona liczba użytkowników końcowych, którzy w tym samym czasie korzystają z usługi, czyli liczba jednocześnie działających instancji aplikacji.

POST /wsBIR/UslugaBIRzewnPubl.svc HTTP/1.1
Host: wyszukiwarkaregon.stat.gov.pl
Content-Type: application/soap+xml; charset=utf-8
sid: {identyfikator-sesji}

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:ns="http://CIS/BIR/PUBL/2014/07" xmlns:dat="http://CIS/BIR/PUBL/2014/07/DataContract">
  <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <wsa:To>https://wyszukiwarkaregon.stat.gov.pl/wsBIR/UslugaBIRzewnPubl.svc</wsa:To>
    <wsa:Action>http://CIS/BIR/PUBL/2014/07/IUslugaBIRzewnPubl/DaneSzukajPodmioty</wsa:Action>
  </soap:Header>
  <soap:Body>
    <ns:DaneSzukajPodmioty>
      <ns:pParametryWyszukiwania>
        <dat:Nip>{nip}</dat:Nip>
      </ns:pParametryWyszukiwania>
    </ns:DaneSzukajPodmioty>
  </soap:Body>
</soap:Envelope>

API REGON od strony technicznej, według instrukcji BIR1.2 i przykładów wywołań GUS

Limity GUS i skutki ich przekroczenia

GUS podaje trzy progi naraz: na godzinę, na minutę i na sekundę, a ich wysokość zależy od pory dnia.

GUS pisze, że przekroczenie limitów nie skutkuje natychmiastową blokadą dostępu, a usługobiorcy, którzy je przekraczają, będą o tym informowani. Instrukcja robi jeden wyjątek: blokada może przyjść od razu, gdy obciążenie wyraźnie spowalnia usługę. Zabronione jest też automatyczne odpytywanie kolejnych numerów po to, żeby ściągnąć wycinek albo cały rejestr; skutkiem jest czasowa niedostępność usługi.

Do limitu wlicza się więcej, niż się wydaje. Według instrukcji przy wyszukiwaniu po liście identyfikatorów każdy z nich liczy się jako osobne zapytanie, a wywołania Zaloguj, GetValue i Wyloguj też zużywają limit. Logowanie przed każdym wyszukiwaniem podwaja więc zużycie, dlatego jedną sesję warto trzymać przez jej 60 minut.

Przy ciągłym ruchu najciaśniejszy okazuje się limit godzinowy, a nie sekundowy. Według tabeli z instrukcji GUS w godzinach 8:00–⁠16:59 trzy zapytania na sekundę dałyby 180 na minutę i 10 800 na godzinę, a GUS dopuszcza wtedy 120 na minutę i 6000 na godzinę. Średnio wychodzi więc około 1,7 zapytania na sekundę, dlatego kolejka musi pilnować wszystkich trzech progów jednocześnie.

Instrukcja liczy limity na jednego użytkownika końcowego, czyli jedną działającą instancję aplikacji. Gdy formularz woła GUS przez Twój serwer, tą instancją jest serwer, więc limit dzielą wszyscy klienci naraz i wszystkie wywołania muszą przejść przez jedną kolejkę po stronie serwera, a nie przez każdą sesję przeglądarki osobno. Duży import, na przykład uzupełnienie tysięcy rekordów w CRM-ie, uruchamiaj w nocy, kiedy limity są najwyższe.

Limity zapytań do API REGON według pory dnia (GUS)

Tabela jest szersza niż ekran: przesuń ją palcem w bok.

Biała lista VAT: search, check, WL2 i limity

Wykaz podatników VAT odpowiada na pytanie, którego rejestr REGON nie zadaje: jaki status VAT miała firma w danym dniu i czy wskazany rachunek był do niej przypisany. Ministerstwo Finansów udostępnia go przez API z metodami search i check, a od 12 października 2026 r. także przez osobne API WL2 do samego statusu.

W metodzie search podajesz NIP, REGON albo numer rachunku oraz dzień, na który chcesz znać stan; jedno zapytanie obejmie najwyżej 30 podmiotów rozdzielonych przecinkami. W odpowiedzi dostajesz nazwę, status VAT (Czynny, Zwolniony albo Niezarejestrowany), numer KRS, jeśli go nadano, adresy i rachunki. Dzień może sięgać pięciu lat poprzedzających rok sprawdzenia, czyli w 2026 r. najwcześniej 1 stycznia 2021 r. (art. 96b ust. 2 ustawy o VAT), a wykaz jest aktualizowany raz na dobę, w dni robocze (ust. 8).

Pola na członków zarządu, prokurentów i wspólników przychodzą przy czynnych i zwolnionych podatnikach puste, bo wykaz tych danych dla nich nie zawiera (art. 96b ust. 4 pkt 2). Przy podmiotach niezarejestrowanych i wykreślonych brakuje z kolei rachunków (ust. 4 pkt 1). Nazwisk zarządu kontrahenta biała lista więc nie dostarczy.

W metodzie check podajesz NIP albo REGON, numer rachunku i datę. Odpowiedź TAK albo NIE mówi, czy tego dnia rachunek był przypisany do podmiotu; dokumentacja precyzuje, że chodzi o podmiot czynny. Obie metody zwracają pole requestId, które Ministerstwo nazywa kluczem elektronicznym: potwierdza, o kogo pytano, na jaki dzień i kiedy. Przy sprawdzeniu przed przelewem zapisz je w bazie razem z datą.

O architekturze decydują limity, które podaje Ministerstwo Finansów. Metodą search złożysz 100 zapytań dziennie o maksymalnie 30 podmiotów, a metodą check zapytasz o 5000 podmiotów. Po wyczerpaniu jednego z limitów dostęp może zostać zablokowany do 0:00, łącznie z wyszukiwarką wykazu na stronie wykazpodatnikowvat.mf.gov.pl. Ministerstwo pisze, że blokowanie jest fakultatywne, ale pewność braku blokady daje tylko trzymanie się limitów.

API WL2, którego adresy Ministerstwo podaje od 12 października 2026 r., odpowiada na węższe pytanie: po NIP-ie i dacie zwraca sam status VAT z identyfikatorem zapytania, bez nazwy, adresu i rachunków, za to z limitem 50 000 zapytań dziennie. Nadaje się do nocnego sprawdzenia, czy kontrahenci z Twojej bazy nadal są czynnymi podatnikami VAT. Do masowej weryfikacji rachunków Ministerstwo publikuje codziennie o północy plik płaski z parami NIP–rachunek zabezpieczonymi funkcją skrótu, tak że istnienie pary potwierdzi tylko ten, kto zna obie wartości.

Do uzupełniania formularza biała lista nadaje się słabo z trzech powodów, które wynikają z dokumentów. Po pierwsze, przy limicie 100 zapytań search dziennie sto pierwsze zamówienie z fakturą tego dnia nie dostanie już podpowiedzi. Po drugie, wykaz obejmuje według art. 96b ust. 1 tylko podmioty zarejestrowane jako podatnicy VAT oraz te, którym odmówiono rejestracji albo które wykreślono, a nie wszystkie firmy. Po trzecie, adres przychodzi jako jeden ciąg tekstu, na przykład „ŚWIĘTOKRZYSKA 12, 00-916 WARSZAWA” w odpowiedzi dla NIP-u Ministerstwa Finansów, który trzeba by samemu dzielić na ulicę, kod i miejscowość.

Adresy właśnie się zmieniają. Ministerstwo podaje adresy ważne od 12 października 2026 r.: wykazpodatnikowvat.mf.gov.pl/api/ dla produkcji i wykazpodatnikowvat-test.mf.gov.pl/api/ dla testów, a WL2 pod ścieżką /api2 tych samych domen. Dotychczasowe wl-api.mf.gov.pl i wl-test.mf.gov.pl nadal figurują na stronie, bez daty wyłączenia. W dniu zmiany nowy adres produkcyjny pokazywał jeszcze stronę „Zapraszamy już wkrótce”, a stary odpowiadał, więc adres trzymaj w konfiguracji. Opis metod w wersji 1.6.1 dodaje w danych podmiotu pole exemptionSmeDate z datą zwolnienia SME.

GET https://wykazpodatnikowvat.mf.gov.pl/api/search/nip/{nip}?date=2026-10-12
GET https://wykazpodatnikowvat.mf.gov.pl/api/search/nips/{nip1},{nip2},{nip3}?date=2026-10-12
GET https://wykazpodatnikowvat.mf.gov.pl/api/check/nip/{nip}/bank-account/{rachunek}?date=2026-10-12
GET https://wykazpodatnikowvat.mf.gov.pl/api2/status/nip/{nip}?date=2026-10-12

{
  "result": {
    "subject": {
      "name": "ABC Jan Nowak",
      "nip": "1111111111",
      "statusVat": "Zwolniony",
      "krs": "0000636771",
      "workingAddress": "ul/ Prosta 49 00-838 Warszawa",
      "accountNumbers": ["90249000050247256316596736"],
      "hasVirtualAccounts": true
    },
    "requestDateTime": "19-11-2019 14:58:49",
    "requestId": "d2n10-84df1a1"
  }
}

KRS: odpis tylko po numerze KRS

Otwarte API Krajowego Rejestru Sądowego, uruchomione przez Ministerstwo Sprawiedliwości 8 marca 2022 r., zwraca dane odpowiadające odpisowi aktualnemu albo pełnemu. Wyszukiwania po NIP w nim nie ma: każda usługa odpisu przyjmuje wyłącznie numer KRS.

Odpis pobierasz zapytaniem GET z numerem KRS i oznaczeniem rejestru: P dla przedsiębiorców albo S dla stowarzyszeń. Według dokumentacji odpowiedź zawsze przychodzi jako JSON, a kody są trzy: 200, 404 („podmiot nie znaleziony”) i 5xx. Odpis pełny zawiera także dane wykreślone.

Biuletyn dzienny i godzinowy zwracają listę podmiotów, w których dokonano wpisów w zadanym dniu (dla dni po 8 grudnia 2021 r.), więc trzymane w bazie odpisy kontrahentów odświeżysz tylko wtedy, gdy się zmieniły. Numery KRS przychodzą w nich bez zer wiodących, na przykład „1109”, więc przed pobraniem odpisu dopełnij je do dziesięciu cyfr.

Imiona, nazwiska i numery PESEL osób ujawnionych w rejestrze usługa anonimizuje; Portal Rejestrów Sądowych powołuje się na obowiązujące przepisy. W pobranym odpisie zostaje z nich pierwszy znak, a resztę zastępują gwiazdki, więc nazwisk członków zarządu stąd nie dostaniesz.

Numer KRS znajdziesz w rejestrze REGON, który przechowuje nazwę i numer rejestru podmiotu, albo w polu krs białej listy. Ścieżka od NIP-u do odpisu ma więc zawsze dwa kroki: najpierw GUS albo biała lista, potem KRS.

Jednoosobowej działalności ani spółki cywilnej w KRS nie ma. Wspólników spółki cywilnej zapisuje rejestr REGON, ale według instrukcji GUS dopiero od 2012 r., więc przy starszej, nieaktualizowanej spółce tej listy może brakować.

GET https://api-krs.ms.gov.pl/api/krs/OdpisAktualny/{krs}?rejestr=P&format=json
GET https://api-krs.ms.gov.pl/api/krs/OdpisPelny/{krs}?rejestr=P&format=json
GET https://api-krs.ms.gov.pl/api/Krs/Biuletyn/2026-10-09
GET https://api-krs.ms.gov.pl/api/Krs/BiuletynGodzinowy/2026-10-09?godzinaOd=08&godzinaDo=12

CEIDG: jednoosobowe działalności

Centralna Ewidencja i Informacja o Działalności Gospodarczej to ewidencja, do której wpisuje się osoby fizyczne prowadzące firmę. Dane z niej udostępnia Hurtownia danych CEIDG i Biznes.gov.pl, ale dostęp wymaga kilku kroków.

Potrzebujesz konta na Biznes.gov.pl i rejestracji w serwisie dane.biznes.gov.pl przez wniosek o dostęp, z akceptacją oświadczenia o ochronie danych osobowych; do hurtowni logujesz się Profilem Zaufanym. Po rejestracji przychodzi mail z informacją o dostępie do aplikacji raportowej i z kluczem do API hurtowni danych. Dokumentacja dla integratorów dotyczy API w wersji 3 i jest dostępna na stronie Akademii Biznes.gov.pl.

Czy w ogóle tego potrzebujesz? Do uzupełnienia nazwy i adresu w formularzu zwykle nie, bo jednoosobowe działalności są także w rejestrze REGON, a jedna integracja z GUS obsłuży i spółki, i JDG. Integracja z CEIDG ma sens, gdy potrzebujesz danych prosto z ewidencji, w której te firmy są wpisywane, albo raportów i statystyk z aplikacji raportowej hurtowni.

VIES dla kontrahentów z UE

VIES sprawdza, czy numer VAT kontrahenta z innego państwa członkowskiego jest ważny w transakcjach wewnątrzwspólnotowych. Nie jest rejestrem firm: Komisja Europejska podkreśla, że nie ma scentralizowanej bazy danych, a każde zapytanie trafia do krajowej bazy państwa, które nadało numer.

Odpowiedź dotyczy wyłącznie dnia zapytania. FAQ VIES mówi wprost, że nie da się sprawdzić, czy numer był ważny w przeszłości, i tym VIES różni się od białej listy, która odpowiada na wskazany dzień. Nazwę i adres dostaniesz tylko tam, gdzie pozwalają na to krajowe przepisy o ochronie danych, a numeru VAT po nazwie albo adresie nie wyszukasz.

Najważniejsza różnica dla programisty: komunikat o niedostępności usługi po stronie państwa członkowskiego nie oznacza, że numer jest nieważny, tylko prosi o ponowienie próby. Krajowe bazy bywają wyłączane na kopie zapasowe i aktualizacje, strona pomocy VIES wymienia stałe okna serwisowe między innymi Niemiec, Włoch i Portugalii, a stan wszystkich krajów zwraca publiczny endpoint check-status. Twój system powinien więc znać trzy stany numeru: ważny, nieważny i niesprawdzony, a ten trzeci ponawiać.

Usługi SOAP i REST mają tę samą funkcjonalność co wyszukiwarka. WSDL zawiera operacje checkVat (kod kraju i numer) oraz checkVatApprox, która przyjmuje też dane kontrahenta do porównania i numer VAT pytającego, a w odpowiedzi ma pole requestIdentifier. Nadmiar równoczesnych zapytań VIES odrzuca z prośbą o ponowienie, a za nadużycia może zablokować adres IP. Całą listę kontrahentów prościej sprawdzić trybem wsadowym na stronie VIES: wgrywasz plik z numerami, a wyniki odbierasz później po tokenie.

Według opisu usługi VIES służy do potwierdzania numerów VAT przy dostawach wewnątrzwspólnotowych (art. 31 rozporządzenia Rady nr 904/2010), a inne wykorzystanie i pobieranie danych jest zabronione. Sprawdzaj w nim kontrahentów, ale nie buduj na nim własnej bazy firm.

GET https://ec.europa.eu/taxation_customs/vies/rest-api/check-status

{
  "vow": { "available": true },
  "countries": [
    { "countryCode": "AT", "availability": "Available" },
    { "countryCode": "BE", "availability": "Available" }
  ]
}

Jak to wpiąć w formularz lub checkout

Samo pobranie danych po NIP to kilka linijek kodu. Trudniejsze jest to, co dzieje się, gdy rejestr nie odpowiada, limit się kończy albo dane z rejestru różnią się od tego, co wpisał klient.

1. Wołaj rejestry tylko z serweraKlucz do API REGON trzymaj w zmiennej środowiskowej na serwerze, nigdy w kodzie strony, gdzie odczyta go każdy odwiedzający. GUS nazywa taki układ zalecaną architekturą, a klucz zapisany na komputerach klientów, z którego każdy łączy się bezpośrednio, opisuje jako źródło problemów: dostawca traci kontrolę nad tym, kto go używa, i może musieć wymieniać go u wszystkich.
2. Sprawdź NIP, zanim zużyjesz zapytanieUsuń spacje, kreski i prefiks kraju, a potem sprawdź, czy zostało dziesięć cyfr. Literówka klienta nie powinna zużywać zapytania z dziennego limitu; API białej listy i tak odpowie na niepoprawny parametr kodem 400.
3. Przepuść wywołania przez jedną kolejkęInstrukcja GUS liczy limity na jedną działającą instancję aplikacji, a gdy klienci łączą się przez Twój serwer, tą instancją jest serwer, więc limit dzielą wszyscy naraz. Kolejka pilnuje progów na sekundę, minutę i godzinę jednocześnie, a przy białej liście liczy zapytania dnia, żeby nie dojść do blokady.
4. Zapamiętuj wynikiTen sam NIP tego samego dnia nie musi trafiać do rejestru dwa razy. Pamięć podręczna z kluczem złożonym z NIP-u i daty oszczędza limit i przyspiesza formularz, gdy klient wraca do koszyka. Dla białej listy zapisuj też requestId i dzień, na który padła odpowiedź.
5. Podpowiadaj, nie nadpisujJeśli klient zaczął wpisywać adres sam, pokaż dane z rejestru jako propozycję do zatwierdzenia jednym kliknięciem. Adres do faktury albo dostawy bywa inny niż adres siedziby z rejestru, a ciche nadpisanie tego, co wpisał człowiek, może skończyć się paczką wysłaną w złe miejsce.
6. Zawsze zostaw ręczne wpisanieRejestr może nie odpowiedzieć, limit może się skończyć, a firma zagraniczna nie ma polskiego NIP-u. Formularz ma wtedy działać jak zwykły formularz, bez komunikatu o błędzie, który blokuje zakup.
7. Oznaczaj, zamiast blokowaćREGON zna daty zawieszenia i zakończenia działalności, a biała lista status VAT. Instrukcja GUS podaje prosty test: podmiot jest aktywny, gdy w raporcie puste są daty zawieszenia, zakończenia, skreślenia i upadłości albo wznowienie nastąpiło po zawieszeniu, a pozostałe z tych dat są puste. Gdy coś nie pasuje, oznacz zamówienie do sprawdzenia przez człowieka, zamiast je odrzucać.
8. Traktuj dane z rejestru jak tekst od klientaInstrukcja GUS ostrzega, że nazwy podmiotów trafiają do usługi w niezmienionej postaci i mogą zawierać fragmenty kodu HTML albo SQL. Nazwę z rejestru wstawiaj więc do strony i do bazy tak samo ostrożnie jak tekst wpisany w formularzu: z escapowaniem w HTML i przez zapytania z parametrami.
9. Zapisz, skąd przyszły daneJeśli dane trafiają do CRM-u, zapisuj obok siebie to, co wpisał klient, i to, co zwrócił rejestr, razem z datą pobrania. Jak zbudować sam przepływ tak, żeby żadne zgłoszenie nie zginęło po drodze, opisuje przewodnik o formularzu kontaktowym połączonym z CRM. Jeśli z tych danych powstaje potem faktura, kolejnym krokiem jest integracja z KSeF przez API.

type DaneZWykazu = { nazwa: string; statusVat: string; krs: string | null; requestId: string };

// Ministerstwo Finansów: metoda search to 100 zapytań dziennie, a po wyczerpaniu limitu
// blokada do 0:00 może objąć także metodę check. 90 zostawia zapas.
const LIMIT_SEARCH_NA_DZIEN = 90;
// Adres ważny od 12.10.2026; dotychczasowy https://wl-api.mf.gov.pl Ministerstwo nadal wymienia.
const WYKAZ_API = process.env.WYKAZ_API ?? 'https://wykazpodatnikowvat.mf.gov.pl';
let licznik = { dzien: '', zapytania: 0 };

// W produkcji licznik i pamięć trzymaj we współdzielonym magazynie z wygasaniem;
// zmienne modułu wystarczą dla jednego procesu.
const pamiec = new Map<string, DaneZWykazu | null>();

export async function bialaListaPoNip(wpisany: string): Promise<DaneZWykazu | null> {
  const nip = wpisany.replace(/\D/g, '');
  if (nip.length !== 10) return null; // formularz prosi o poprawienie numeru, limit zostaje nietknięty
  const dzien = new Intl.DateTimeFormat('en-CA', { timeZone: 'Europe/Warsaw' }).format(new Date()); // RRRR-MM-DD
  const klucz = `${nip}:${dzien}`;
  if (pamiec.has(klucz)) return pamiec.get(klucz) ?? null;

  if (licznik.dzien !== dzien) licznik = { dzien, zapytania: 0 }; // nowy dzień, nowy limit
  if (licznik.zapytania >= LIMIT_SEARCH_NA_DZIEN) return null; // do północy tylko ręczne wpisanie
  licznik.zapytania += 1;

  try {
    const odpowiedz = await fetch(`${WYKAZ_API}/api/search/nip/${nip}?date=${dzien}`, {
      headers: { Accept: 'application/json' },
      signal: AbortSignal.timeout(5000),
    });
    if (!odpowiedz.ok) return null; // 400 to niepoprawny parametr; każdy inny błąd: ręczne wpisanie
    const { result } = await odpowiedz.json();
    const dane: DaneZWykazu | null = result?.subject
      ? {
          nazwa: result.subject.name,
          statusVat: result.subject.statusVat,
          krs: result.subject.krs ?? null,
          requestId: result.requestId,
        }
      : null;
    pamiec.set(klucz, dane);
    return dane;
  } catch {
    return null; // przekroczony czas albo błąd sieci: formularz działa dalej bez podpowiedzi
  }
}

Urzędowe API czy płatny pośrednik

W wynikach wyszukiwania obok stron urzędów pojawiają się płatne usługi, które zbierają kilka rejestrów pod jednym API. Ten przewodnik ich nie porównuje, ale pomaga zdecydować, czy ich potrzebujesz.

Źródło urzędowe wybierasz, gdy potrzebujesz jednego albo dwóch rejestrów, mieścisz się w limitach i chcesz wiedzieć, skąd pochodzi każda dana i z jakiego dnia. Koszt jest po Twojej stronie w innej postaci: prośba o klucz do GUS, klient SOAP, kolejka pod limity i osobna obsługa przerw w każdym rejestrze.

Pośrednik ma sens, gdy potrzebujesz wielu rejestrów naraz i nie chcesz utrzymywać kilku integracji. Zanim podpiszesz umowę, zapytaj, z których rejestrów i z jakiego dnia pochodzą dane oraz co usługa zwraca, gdy rejestr źródłowy nie odpowiada. Formularz i tak ma działać także wtedy, gdy żadne API nie odpowie.

Pytania i odpowiedzi