Szczegóły techniczne dla osoby, która będzie odbierać wdrożenie.
Jak NIP zamienia się w dane organizacji
NIP trzymam w polu niestandardowym organizacji. Gdy powstaje nowa organizacja albo ktoś zmienia NIP, Pipedrive wysyła webhook (Webhooks v2, obiekt organization, akcje create i change). Integracja sprawdza sumę kontrolną NIP-u i pyta API REGON GUS (BIR1.2). Klucz do niego GUS wydaje bezpłatnie na wniosek wysłany e-mailem. GUS zwraca nazwę, adres siedziby, formę prawną, REGON, PKD, a dla spółek także numer KRS.
Numer KRS otwiera drugie źródło: otwarte API KRS Ministerstwa Sprawiedliwości (api-krs.ms.gov.pl), które nie wymaga klucza, ale szuka tylko po numerze KRS, nie po NIP-ie. Dlatego GUS jest zawsze pierwszy. Z odpisu aktualnego biorę skład zarządu, sposób reprezentacji i kapitał zakładowy. Status VAT i rachunki bankowe dociąga API Białej listy Ministerstwa Finansów. Biała lista, REGON i KRS dla dowolnej firmy są też w naszej wyszukiwarce po NIP.
Co widać w Pipedrive
Nazwa organizacji i adres trafiają do standardowych pól, więc działa mapa, wyszukiwarka i filtry po mieście. REGON, KRS, PKD, forma prawna i status VAT lądują w polach niestandardowych, po których da się filtrować i budować segmenty. W panelu organizacji może się pojawić przycisk „Odśwież z GUS” (rozszerzenie aplikacji Pipedrive), jeśli handlowcy chcą ręcznie pobrać dane jeszcze raz.
Zapętlenia, duplikaty i limity
Zapis danych przez API sam wywołuje webhook change. Integracja rozpoznaje własne zmiany i porównuje poprzednią wartość NIP-u, więc nie odpytuje GUS w kółko. Przed utworzeniem nowej organizacji można też sprawdzić, czy ten NIP już jest w bazie, i zamiast duplikatu podpowiedzieć istniejący rekord.
GUS ogranicza zapytania (w godzinach 8-17 do 3 na sekundę, 120 na minutę i 6000 na godzinę, w nocy do 10 000 na godzinę), Biała lista do 100 wyszukiwań dziennie, a Pipedrive ma dzienny budżet API zależny od planu i liczby licencji. API i webhooki są dostępne na każdym planie Pipedrive. Webhooki nie zużywają budżetu API, a zapis danych do organizacji to jedno lub dwa wywołania. Wszystko idzie więc przez kolejkę z ponowieniami, a masowe uzupełnianie starej bazy działa nocą.
Przypadki brzegowe
Spółki cywilne mają NIP spółki i osobne wpisy wspólników w CEIDG. Firmy z oddziałami mają w GUS jednostki lokalne z własnymi adresami. Podmioty wykreślone GUS nadal zwraca, ale z datą zakończenia działalności, co integracja oznacza w organizacji zamiast po cichu nadpisywać dane.