GUS BIR API — dlaczego weryfikacja NIP przez REGON jest trudniejsza, niż wygląda

Dlaczego REGON jest punktem wejścia

Systemy księgowe i CRM trzymają NIP. Rejestry chcą swoich identyfikatorów: KRS numeru KRS, część usług numeru REGON. Baza Internetowa REGON (GUS BIR) przyjmuje NIP i zwraca komplet: nazwę, adres, PKD, formę prawną oraz — co najważniejsze — numer KRS, jeśli podmiot go ma.

Bez tego mostu nie da się sensownie odpytać KRS-u zaczynając od faktury.

Cztery rzeczy, które zaskakują przy pierwszej integracji

1. To SOAP, nie REST. Zapytania i odpowiedzi w XML, komunikacja przez usługę sieciową w starszym stylu. Da się to obsłużyć w każdym języku, ale nie jest to fetch i JSON.parse.

2. Sesja. Najpierw logujesz się kluczem i dostajesz identyfikator sesji, który trzeba dołączać do kolejnych zapytań i odnawiać po wygaśnięciu. Integracja bezstanowa wymaga więc własnego zarządzania sesją.

3. Różne raporty dla różnych form prawnych. Osoba fizyczna prowadząca działalność zwraca inny zestaw danych niż spółka prawa handlowego. Jeden parser „na wszystko” rozsypie się na pierwszej jednoosobowej działalności.

4. REGON dziewięcio- i czternastoznakowy. Podstawowy ma 9 znaków, jednostki lokalne 14. Walidacja sumy kontrolnej jest inna dla każdego z nich.

Jednoosobowe działalności — osobna historia

Dla JDG dane w REGON bywają uboższe, a pełniejszy obraz siedzi w CEIDG — osobnym rejestrze, z osobnym kluczem dostępu. Sensowna integracja odpytuje REGON, a gdy trafi na działalność gospodarczą, sięga po uzupełnienie do CEIDG. To kolejne źródło do utrzymania.

Pułapka, która nie rzuca wyjątku

Kod PKD w różnych rejestrach ma różny format zapisu. GUS potrafi zwrócić 1920Z, KRS ten sam kod jako 19.20.Z. Nic się nie wywala — po prostu porównanie kodów z dwóch źródeł nigdy nie trafia, filtry po branży cicho nie działają, a raporty pokazują puste kategorie.

Najgorsze błędy integracji z rejestrami nie rzucają wyjątku. Zwracają wynik, który wygląda poprawnie i jest nieprawdziwy.

Do tego dochodzi konsekwencja operacyjna: po poprawieniu takiego parsowania trzeba unieważnić cache, bo dane zapisane starym formatem zostaną w nim ze starym błędem.

Co z tym robić

Albo obsłużyć to u siebie — sesja, dwa formaty REGON, dwa źródła dla JDG, normalizacja PKD — albo użyć warstwy, która ma to już zrobione i zwraca jeden ustandaryzowany kształt niezależnie od formy prawnej podmiotu.

Parametry i przykłady: dokumentacja API REGON / GUS.

Materiał ma charakter informacyjny. Źródłem danych jest rejestr REGON prowadzony przez Główny Urząd Statystyczny oraz CEIDG. Zasady dostępu i limity ustalają te instytucje.