Dane z GUS w HubSpot jednym kliknięciem. Jak działa karta firmy z rejestrem REGON

Co robi karta

W każdym polskim CRM powtarza się ta sama czynność. Handlowiec dodaje firmę, otwiera w drugiej karcie wyszukiwarkę REGON, wkleja NIP i przepisuje nazwę, adres, REGON i PKD. Pole po polu, z literówkami, które potem wracają na fakturach.

Demo zamienia to w jeden przycisk na rekordzie firmy w HubSpot: „Pobierz z GUS”. Karta bierze NIP z rekordu, pyta rejestr REGON, pokazuje porównanie w trzech kolumnach (pole, wartość w HubSpot, wartość z GUS) i zapisuje dopiero po kliknięciu „Zapisz”. Na osi czasu firmy zostaje notatka „Uzupełniono z GUS” z listą zmienionych pól. Gdy firma jest wykreślona z REGON albo to jednoosobowa działalność, karta ostrzega przed zapisem.

Gdzie stoi serwer i dlaczego nie w HubSpot

Karty aplikacji w HubSpot to komponenty React, które HubSpot renderuje u siebie. Nie mogą wołać dowolnych adresów. Są dwie drogi:

• Funkcje serverless w projekcie HubSpot. Od wersji platformy 2026.03 wróciły do aplikacji, ale aplikację, która je zawiera, da się zainstalować tylko na koncie Enterprise. Na koncie testowym dewelopera działa, u klienta na planie Free czy Starter już nie.
• hubspot.fetch() do własnego serwera. Adres musi być HTTPS i wpisany do listy permittedUrls.fetch w konfiguracji aplikacji (wpisy działają jak prefiksy). HubSpot podpisuje każde żądanie i dopisuje do adresu portalId, userId i appId.

O wyborze zdecydował GUS. We wniosku o klucz produkcyjny podaje się adresy IP, z których pójdą zapytania, a identyfikator sesji działa tylko z adresu, który go uzyskał. Serverless z losowym IP wyjściowym gryzie się z jednym i drugim. Dlatego serwer to mała usługa Node na VPS ze stałym adresem, za Caddy, a karta rozmawia z nią przez hubspot.fetch.

Rozmowa z GUS bez biblioteki SOAP

Usługa to BIR1.2 (API REGON). Wystarczą trzy metody: Zaloguj (klucz w zamian za identyfikator sesji), DaneSzukajPodmioty (wyszukiwanie po NIP) i DanePobierzPelnyRaport (pełny raport dla REGON-u, dla spółek BIR12OsPrawna i BIR12OsPrawnaPkd). Więcej o kluczach, limitach i sesji jest w przewodniku po API REGON.

Zapytanie to koperta SOAP 1.2 z nagłówkami WS-Addressing, wysyłana zwykłym fetch. Identyfikator sesji nie trafia do koperty, tylko do nagłówka HTTP sid. Odpowiedź przychodzi jako multipart/related (MTOM), ale parser MIME nie jest potrzebny: wystarczy wyciąć tekst między <DaneSzukajPodmiotyResult> a znacznikiem zamykającym. To dokument XML zapisany jako tekst, więc po jednym odkodowaniu encji dostajesz płaski <root><dane>…</dane></root>, po jednym bloku <dane> na wiersz.

Co kosztowało najwięcej czasu:

• GetValue jest w innym kontrakcie. Wszystkie metody używają akcji z przestrzeni IUslugaBIRzewnPubl, a GetValue (np. StatusSesji) z http://CIS/BIR/2014/07/IUslugaBIR/GetValue. Wysłana z akcją publiczną kończy się błędem ActionNotSupported.
• Pusty wynik to nie zawsze brak firmy. Może też oznaczać wygasłą sesję. Przy pustym wyniku karta sprawdza StatusSesji, w razie potrzeby loguje się ponownie i powtarza zapytanie raz, zanim powie, że nic nie znalazła.
• Kod pocztowy w dwóch formatach. Wyszukiwanie zwraca 00-925, pełny raport 00925.
• Nazwy mogą zawierać znaczniki. GUS sam ostrzega przed fragmentami HTML lub SQL w nazwach, więc każda wartość jest czyszczona, zanim trafi do CRM.
• Jednoosobowa działalność to inny raport. Wiersz z Typ równym F to osoba fizyczna. Raport dla osób prawnych nie pasuje, karta pokazuje ostrzeżenie, a dane traktuje jak dane osobowe.
• Status wynika z dat. „Aktywna”, „zawieszona” czy „wykreślona” liczy się z dat zawieszenia, wznowienia, zakończenia działalności i skreślenia z REGON.

Podpis żądań HubSpot

Żądania z hubspot.fetch mają nagłówki X-HubSpot-Signature-v3 i X-HubSpot-Request-Timestamp. Podpis to HMAC-SHA256 z metody, pełnego adresu, surowej treści i znacznika czasu, liczony kluczem client secret aplikacji i zakodowany w base64. Dwa szczegóły: część znaków zakodowanych procentowo w adresie trzeba przed liczeniem odkodować, a żądania starsze niż pięć minut odrzucić.

Pełny adres to adres publiczny, razem z parametrami dopisanymi przez HubSpot, a nie to, co przekazuje dalej reverse proxy. Jeśli podpis nie zgadza się przy każdym żądaniu, od tego warto zacząć.

Zapis tylko po zatwierdzeniu

Karta niczego nie zapisuje sama. „Pobierz z GUS” woła GET /gus/lookup, serwer zwraca dane z rejestru i od razu wartości właściwości HubSpot, a karta rysuje porównanie. Zmienione wiersze są pogrubione, stara wartość przekreślona, niezmienione wyszarzone.

„Zapisz” wysyła tylko zmienione pola na POST /gus/apply. Serwer przyjmuje wyłącznie ustaloną listę właściwości, aktualizuje firmę przez CRM API i tworzy powiązaną notatkę. Gdy aktualizacja się uda, a notatka nie, karta i tak pokazuje, że dane zapisano. Komunikat „nic nie zapisano” skończyłby się ponownym kliknięciem i podwójnym zapisem.

Czego demo jeszcze nie robi

Demo obejmuje tylko GUS. Pełna integracja dociąga też odpis z KRS dla spółek (zarząd, kapitał), CEIDG dla jednoosobowych działalności i status z Białej listy, uruchamia się przy nowych firmach przez webhooki i okresowo sprawdza istniejących klientów. Zakres i ceny są na stronie integracji HubSpot z GUS, KRS i CEIDG. Jakie dane z Białej listy, REGON i KRS przychodzą dla konkretnej firmy, sprawdzisz w wyszukiwarce po NIP.