Dane firmy z GUS po NIP. Jak działa API REGON (BIR1.2) i co naprawdę zwraca

Co to właściwie jest „API GUS”

„Dane z GUS po NIP” to prawie zawsze jedna usługa: BIR1, czyli Baza Internetowa REGON, udostępniająca dane z rejestru REGON. Inne API GUS (TERYT, Bank Danych Lokalnych) z danymi firm nie mają nic wspólnego.

REGON jest przy tym rejestrem wtórnym. Spółki trafiają do niego z KRS, jednoosobowe działalności z CEIDG, szkoły z RSPO. Instrukcja techniczna GUS mówi wprost, że aktualność danych zależy od rejestrów pierwotnych, a baza produkcyjna BIR synchronizuje się z bazą transakcyjną co kilka minut. Wynikają z tego dwie rzeczy: świeżo założona firma może w REGON jeszcze nie istnieć, a dane działalności wpisanych przed 1 lipca 2011 roku bywają nieaktualne, bo wtedy obowiązek zgłaszania zmian do urzędu statystycznego spoczywał na przedsiębiorcy i często nie był dopełniany.

Opis usługi, limity i paczka z instrukcją techniczną, schematami XSD i przykładami są na api.stat.gov.pl.

BIR1.1 czy BIR1.2

Na stronie GUS figurują dwie aktualne wersje: BIR1.1 (od maja 2019) i BIR1.2 (od grudnia 2024, na produkcji od 1 stycznia 2025). To nie są dwa serwisy. Adres i WSDL są te same, wyszukiwanie się nie zmieniło, a „wersja” to nazwa raportu, o który prosisz: BIR11OsPrawna albo BIR12OsPrawna.

BIR1.2 powstał z powodu PKD 2025. Raporty z kodami PKD w wersji 1.2 (BIR12OsPrawnaPkd, BIR12OsFizycznaPkd i dwa dla jednostek lokalnych) mają dodatkowe pole z wersją klasyfikacji, na przykład praw_pkdWersja z wartością 2007 albo 2025. Przy okazji wydłużono numer lokalu z 10 do 20 znaków, a stare raporty BIR11 dla zgodności wstecznej przycinają go do 10 znaków. Od stycznia 2026 jest jeszcze raport BIR121JednLokalnaOsPrawnej, który dla jednostki lokalnej zwraca jej własny NIP.

Praktycznie: we wrześniu 2026 nowa integracja powinna używać raportów BIR12 i zapisywać kod PKD razem z wersją klasyfikacji. Stara integracja na BIR11 działa dalej, ale może po cichu gubić końcówki numerów lokali.

Dostęp: klucz, środowisko testowe, adresy IP

Środowisko testowe działa bez rejestracji, z publicznym kluczem abcde12345abcde12345. Ma pełną bazę, ale nieaktualizowaną: większość danych pochodzi z 8 listopada 2014 roku, a nazwiska i adresy są zanonimizowane. Nadaje się do sprawdzenia kopert i parsowania, nie do testów na danych klienta.

Klucz produkcyjny jest bezpłatny. Zamawia się go zwykłym e-mailem na regon_bir@stat.gov.pl, podając:

• pełną nazwę i REGON podmiotu,
• imię, nazwisko, e-mail i telefon osoby do kontaktu,
• przybliżoną liczbę użytkowników, którzy będą jednocześnie korzystać z usługi,
• adresy IP, z których będą szły zapytania.

Adresy IP są wymagane, gdy zapytania idą przez serwer dostawcy oprogramowania, a przy stałej puli GUS zaleca je podać dla diagnostyki. Czasu oczekiwania na klucz GUS nie podaje, więc nie planowałbym startu produkcji na dzień po wysłaniu maila.

GUS opisuje przy tym trzy układy: zalecany (klucz trzyma dostawca, zapytania idą przez jego serwer ze znanych IP), dopuszczalny (klucz dostawcy zaszyty w aplikacji instalowanej u klientów, z ryzykiem wymiany klucza u wszystkich po nadużyciu) i niedopuszczalny (każdy użytkownik końcowy z własnym kluczem). Integracja CRM powinna iść pierwszą drogą.

Jak wygląda rozmowa z API

To SOAP 1.2 z nagłówkami WS-Addressing. REST-a ani JSON-a nie ma. Sekwencja wygląda tak:

Zaloguj(klucz)                         → sid, 20 znaków
DaneSzukajPodmioty(Nip)       + sid    → Regon, Typ, SilosID
DanePobierzPelnyRaport(Regon, raport) + sid
pusty wynik?  GetValue("KomunikatKod")
Wyloguj(sid)

Identyfikator sesji idzie nie w kopercie, tylko w nagłówku HTTP sid. Każda koperta musi mieć wsa:To i wsa:Action, których SoapUI sam nie dodaje. Wyszukiwanie przyjmuje jeden identyfikator (Nip, Regon, Krs) albo do 20 naraz (Nipy, Regony9zn, Regony14zn, Krsy). Jeśli podasz kilka parametrów, GUS szuka tylko po pierwszym.

Trzy rzeczy, które sprawdziłem na środowisku testowym i które łamią typowego klienta HTTP:

• Odpowiedź przychodzi jako MTOM, czyli multipart/related z kopertą w środku, nawet gdy wysyłasz zwykłe application/soap+xml. Klient, który oczekuje czystego XML, nie sparsuje nawet udanego logowania.
• Wynik to XML w stringu. Pole DaneSzukajPodmiotyResult zawiera dokument <root><dane>… zapisany jako tekst z encjami < i >. Trzeba go wyciągnąć i sparsować drugi raz.
• GetValue ma inną przestrzeń nazw niż reszta metod (http://CIS/BIR/2014/07 zamiast http://CIS/BIR/PUBL/2014/07). Skopiowanie koperty od Zaloguj i podmiana nazwy metody nie zadziała.

Pusty wynik to nie zawsze „brak firmy”

„Nie znaleziono” nie przychodzi jako błąd HTTP. Dostajesz status 200 i w środku wyniku ErrorCode 4 z komunikatem po polsku i angielsku. Całkiem pusty wynik oznacza zwykle coś innego i wtedy trzeba zapytać GetValue("KomunikatKod"):

Kod	Znaczenie
0	poprzednia operacja wykonana poprawnie
2	za dużo identyfikatorów w jednym wyszukiwaniu
4	nie znaleziono podmiotu (często: raport dla osoby prawnej zamiast fizycznej lub odwrotnie)
5	nieprawidłowa lub pusta nazwa raportu
7 lub pusty	brak sesji: wygasła albo sid jest nieprawidłowy

Integracja, która każdą pustą odpowiedź zapisuje jako „firma nie istnieje”, prędzej czy później oznaczy tak żywego klienta tylko dlatego, że wygasła sesja.

Sesja, IP i limity

Sesja żyje 60 minut albo do wywołania Wyloguj. Jest też zależność, o której łatwo nie wiedzieć przy skalowaniu: przez load balancing po stronie GUS sid nie zostanie rozpoznany, jeśli pochodzi z innego adresu IP niż bieżące żądanie. Jeśli masz kilka instancji albo serverless z losowym IP wyjściowym, każda instancja musi logować się sama, a nie dzielić się sesją przez cache. Dodatkowo co noc o 3:20 GUS czyści pulę na serwerze i wszystkie aktywne wtedy sesje są zamykane. Nocny import, który loguje się raz o 3:00, wysypie się w połowie.

Limity GUS publikuje na stronie usługi i w instrukcji:

Godziny	Na godzinę	Na minutę	Na sekundę
8:00 do 16:59	6 000	120	3
6:00 do 7:59 i 17:00 do 21:59	8 000	150	3
22:00 do 5:59	10 000	200	4

Dwa szczegóły z instrukcji zmieniają rachunek. Po pierwsze, Zaloguj, GetValue i Wyloguj też wliczają się do limitów, więc logowanie przed każdym zapytaniem zjada połowę budżetu. Po drugie, przy wyszukiwaniu wielu identyfikatorów naraz każdy liczy się osobno, więc paczka 20 NIP-ów to 20 zapytań, a nie jedno. Przekroczenie nie kończy się natychmiastową blokadą, GUS zapowiada raczej kontakt z usługobiorcą. Wyjątkiem jest automatyczne przechodzenie po kolejnych numerach REGON w celu ściągnięcia rejestru: tego instrukcja wprost zabrania, a skutkiem jest czasowe odcięcie od usługi.

Wniosek: kolejka z ponowieniami, jedna sesja na instancję, a masowe uzupełnianie starej bazy wieczorem lub w nocy.

Osoby fizyczne, oddziały i dwa rodzaje REGON-u

Tu leży większość błędów w danych, bo integracje zakładają, że jeden NIP to jeden rekord.

Wynik wyszukiwania ma pole Typ: P (jednostka prawna, czyli spółka, fundacja, ale też spółka cywilna), F (osoba fizyczna prowadząca działalność), LP i LF (jednostki lokalne jednych i drugich). Od typu zależy, który raport wolno potem pobrać. Na F raport BIR12OsPrawna zwróci kod 4, choć firma istnieje.

Osoba fizyczna ma do tego pole SilosID: 1 to działalność z CEIDG, 2 rolnicza, 3 tak zwana pozostała (na przykład komornik, notariusz), 4 skreślona przed 8 listopada 2014 roku. Jedna osoba może prowadzić kilka takich działalności pod tym samym 9-cyfrowym REGON-em, z różnymi adresami. Wyszukiwanie po NIP zwraca wtedy kilka wierszy, a dla każdego trzeba pobrać osobny raport.

REGON ma 9 albo 14 cyfr. Czternaście ma jednostka lokalna, na przykład oddział, a pierwsze 9 cyfr jest wspólne z podmiotem macierzystym. Zera wiodące są znaczące: GUS podaje przykład, że REGON to 000000023, a nie 23. Pole liczbowe w CRM albo w arkuszu po cichu je obetnie, więc REGON i NIP zawsze trzymaj jako tekst.

Status firmy trzeba policzyć samemu. Instrukcja GUS podaje algorytm: osoba prawna jest aktywna, jeśli puste są daty zawieszenia, zakończenia działalności, skreślenia z REGON, orzeczenia o upadłości i zakończenia postępowania upadłościowego, albo jeśli data wznowienia jest późniejsza niż data zawieszenia. Dla osoby fizycznej sprawdza się to osobno dla każdej działalności, a podmiot jest aktywny, jeśli aktywna jest choć jedna. Podmioty wykreślone GUS nadal zwraca, z wypełnionymi datami.

Wspólników spółki cywilnej zwraca osobny raport, ale REGON rejestruje ich dopiero od 2012 roku. Dla starszych spółek, których nikt nie aktualizował, tych danych po prostu nie ma.

Walidacja, bezpieczeństwo i RODO

Sprawdź NIP przed wysłaniem. Suma kontrolna to wagi 6, 5, 7, 2, 3, 4, 5, 6, 7 dla pierwszych dziewięciu cyfr, suma modulo 11 musi być równa dziesiątej cyfrze (wynik 10 oznacza nieprawidłowy NIP). Możesz to sprawdzić w walidatorze NIP, który pokazuje obliczenie krok po kroku. Kilka linijek kodu oszczędza limit i daje handlowcowi natychmiastowy komunikat o literówce.

Traktuj nazwy jak dane od użytkownika. GUS w instrukcji osobno ostrzega, że nazwy podmiotów, które trafiają do REGON między innymi z CEIDG, są przekazywane dalej bez zmian i mogą zawierać fragmenty kodu HTML lub SQL. Escapowanie przy wyświetlaniu i zapytania parametryzowane to tu nie teoria, tylko wymóg.

Jednoosobowa działalność to dane osobowe. Imię, nazwisko i adres wykonywania działalności, który u wielu mikrofirm jest adresem domowym, są danymi osobowymi. Jeśli budujesz z nich bazę do sprzedaży, pojawia się obowiązek informacyjny z art. 14 RODO wobec osób, których dane pozyskujesz nie od nich samych. To temat dla osoby od ochrony danych, nie dla kodu.

Czego GUS nie da i skąd to wziąć

Potrzebujesz	Źródło	Dostęp	Szuka po
nazwa, adres, forma prawna, PKD, daty, numer KRS	REGON, BIR1.2	bezpłatny klucz e-mailem	NIP, REGON, KRS
status VAT, rachunki bankowe	Biała lista MF	bez klucza	NIP, REGON, rachunek
zarząd, reprezentacja, kapitał	otwarte API KRS	bez klucza	tylko numer KRS
status i szczegóły jednoosobowej działalności	API CEIDG	rejestracja i token	NIP, REGON i inne

Biała lista pozwala na 100 wyszukiwań dziennie, każde o maksymalnie 30 podmiotów, a metodą sprawdzającą na 5000 podmiotów; po wyczerpaniu limitu dostęp może być zablokowany do północy, łącznie z wyszukiwarką na stronie. Otwarte API KRS nie szuka po NIP, więc numer KRS bierze się najpierw z GUS, a imiona, nazwiska i PESEL członków zarządu są w odpowiedzi zamaskowane gwiazdkami (sprawdziłem na odpisie aktualnym). API CEIDG w wersji 3 wymaga konta na biznes.gov.pl i rejestracji w hurtowni danych, a limity to 50 żądań na 3 minuty i 1000 na godzinę, z karencją 180 sekund liczoną od ostatniego żądania po przekroczeniu pierwszego progu.

Kolejność, która działa w praktyce: suma kontrolna NIP, potem GUS, który mówi, z jakim typem podmiotu masz do czynienia, potem KRS dla spółek albo CEIDG dla działalności, a na końcu Biała lista, jeśli dane mają trafić do finansów.

Gotowe narzędzie czy własna integracja

Uczciwie: przy kilku nowych firmach w tygodniu własna integracja się nie zwróci. Tańsze drogi są trzy. Wyszukiwarka w przeglądarce: REGON albo nasza wyszukiwarka firm po NIP, która pokazuje Białą listę, REGON i KRS na jednym ekranie. Usługa pośrednia, na przykład nip24.pl, która opakowuje GUS, KRS i Białą listę i ma gotowy moduł w Make; w cenniku z 26 września 2026 najtańszy plan to 49 zł netto miesięcznie za 1000 zapytań. Albo aplikacja z marketplace’u CRM, jak Integracja GUS KRS od MAN Digital dla HubSpot, która w darmowym planie uzupełnia dane z GUS, a KRS dociąga po wykupieniu osobnego planu register.io.

Własna integracja zaczyna mieć sens, gdy potrzebujesz kilku źródeł naraz (GUS, KRS, CEIDG i Biała lista), gdy trzeba jednorazowo uzupełnić dużą istniejącą bazę, gdy dane mają trafić do Twoich własnych pól i procesów, gdy chcesz okresowo pilnować zmian statusu kontrahentów albo gdy zapytania o klientów nie mogą wychodzić do pośrednika. Tak zbudowane są moje integracje Pipedrive z GUS i KRS oraz HubSpot z GUS, KRS i CEIDG.

Checklist przed wdrożeniem

1. Czy integracja używa raportów BIR12 i zapisuje wersję PKD.
2. Czy NIP jest walidowany sumą kontrolną przed wysłaniem.
3. Czy klient HTTP obsługuje odpowiedź MTOM i drugie parsowanie XML ze stringa.
4. Czy pusta odpowiedź jest odróżniana od „nie znaleziono” przez GetValue.
5. Czy każda instancja ma własną sesję i czy nocne zadania przeżyją 3:20.
6. Czy kolejka mieści się w limitach, licząc logowanie i każdy NIP w paczce.
7. Czy rozróżniasz Typ i SilosID i obsługujesz kilka wierszy na jeden NIP.
8. Czy REGON i NIP są trzymane jako tekst, a nazwy escapowane.

Jeśli chcesz, żebym przeszedł tę listę na Twoim CRM, opisz go w formularzu niżej. Odpowiem, co trzeba zrobić i ile to kosztuje, także wtedy, gdy wniosek będzie brzmiał „wystarczy gotowa aplikacja”.