CEIDG API, REGON API i wykaz VAT: ile realnie kosztuje własna integracja z rejestrami

Podpięcie się do CEIDG API, REGON API, API KRS i API wykazu podatników VAT nic nie kosztuje w opłatach: wszystkie cztery interfejsy są bezpłatne. Koszt leży gdzie indziej, bo każdy z nich ma inny protokół, inny sposób uwierzytelnienia, inne limity i inny format odpowiedzi, więc zamiast jednej integracji budujesz cztery i utrzymujesz je w nieskończoność. Ten tekst jest po to, żeby policzyć tę pracę przed decyzją, a nie w połowie sprintu.

Pytanie pada zwykle w tym samym momencie: system księgowy albo wewnętrzny CRM ma przy kontrahencie pokazywać status VAT, numer rachunku z wykazu i dane rejestrowe, ktoś sprawdza, że państwowe API są darmowe, i zadanie trafia do backlogu jako „dwa dni robocze". Po dwóch tygodniach okazuje się, że GUS odpowiada po SOAP, CEIDG wymaga rejestracji po token, a wykaz VAT przyjmuje maksymalnie trzydzieści numerów naraz i żąda daty w każdym zapytaniu.

Cztery rejestry, cztery zupełnie różne interfejsy

Warto najpierw zobaczyć je obok siebie, bo dopiero wtedy widać, dlaczego to nie jest jedna robota powtórzona cztery razy.

Najbardziej niedoceniana jest pozycja druga. API REGON to jedno z najstarszych publicznych API w Polsce i nadal działa po SOAP: najpierw wysyłasz klucz użytkownika i dostajesz klucz sesji, potem przekazujesz go w nagłówku przy każdym kolejnym wywołaniu, a odpowiedź przychodzi jako XML zawinięty w XML. Żadna z popularnych bibliotek HTTP nie obsłuży tego z marszu. W praktyce to kilka dni pracy na sam adapter, zanim jeszcze padnie pierwsze poprawne zapytanie produkcyjne.

Czego nie ma w wycenie, a jest w rachunku

Pierwszą wersję integracji da się napisać szybko. Rachunek przychodzi przy drugim i trzecim miesiącu, kiedy pojawiają się rzeczy, których nie widać w dokumentacji.

Rejestry milczą i robią to bez uprzedzenia

Każde z tych API bywa niedostępne. GUS ma okna serwisowe, wykaz VAT aktualizuje się raz na dobę i w trakcie aktualizacji potrafi odpowiadać wolniej, a KRS miewa przerwy w środku dnia. Jeżeli sprawdzenie kontrahenta jest wpięte w ścieżkę księgowania faktury, każda taka przerwa zatrzymuje pracę ludzi. Trzeba więc dołożyć warstwę pamięci podręcznej, rozsądny czas oczekiwania, ponowienia z odstępem i sensowny stan pusty zamiast komunikatu o błędzie. To nie jest opcja, to warunek, żeby integracja nadawała się do codziennego użytku.

Dane z czterech źródeł nie pasują do siebie

Ta sama firma ma w KRS pełną nazwę z formą prawną, w wykazie VAT nazwę skróconą, a w rejestrze GUS jeszcze inną. Adresy różnią się interpunkcją i sposobem zapisu numeru lokalu. Data rozpoczęcia działalności w CEIDG nie jest tym samym co data rejestracji jako podatnika VAT. Zestawienie tego w jedną kartę firmy, która nie kłamie, to osobny problem do rozwiązania, i pojawia się dopiero wtedy, gdy dane zaczną trafiać do interfejsu, który ogląda człowiek.

Zmiany po stronie państwa nie są Twoim harmonogramem

Hurtownia danych CEIDG ma dziś API w wersji drugiej, co samo w sobie mówi, że pierwsza kiedyś przestała wystarczać. Rejestry zmieniają formaty, dokładają pola i wycofują stare końcówki, a każda taka zmiana wraca do Twojego backlogu w terminie ustalonym przez kogoś innego. To koszt, który nie kończy się razem z wdrożeniem, tylko ciągnie się przez cały czas życia systemu.

Integracja musi gdzieś stać

Klucz do REGON nie powinien siedzieć w aplikacji klienckiej, bo to naruszenie regulaminu usługi, a poza tym oddaje limit zapytań w cudze ręce. Rekomendowana architektura to własny serwer pośredniczący, który trzyma klucze, kontroluje liczbę wywołań i buforuje odpowiedzi. A to znaczy jeszcze jedną maszynę do utrzymania: hosting, certyfikat, monitoring i ktoś, kto odbierze telefon, gdy przestanie odpowiadać w piątek po południu. Przy takiej roli warto od razu wybrać serwer z polskim wsparciem technicznym, bo przy awarii pośrednika zatrzymuje się księgowanie, a nie strona wizytówkowa.

Kiedy własna integracja faktycznie się opłaca

Nie zawsze jest to zły pomysł. Są sytuacje, w których zbudowanie tego u siebie jest decyzją poprawną i tańszą w dłuższym okresie.

Granica przebiega w miejscu, które łatwo przeoczyć: czy dane rejestrowe są Twoim produktem, czy tylko pomocą przy innym produkcie. W pierwszym przypadku budujesz. W drugim płacisz za to, żeby ktoś inny utrzymywał cztery adaptery i pilnował zmian po stronie rejestrów.

Jak policzyć to u siebie w piętnaście minut

Zamiast szacowania „na oko" warto przejść przez cztery pytania i zapisać odpowiedzi.

1. Ile sprawdzeń miesięcznie? Policz faktury, które przechodzą przez próg 15 000 zł brutto, i nowych kontrahentów. To liczba, która decyduje o wszystkim dalej.
2. Które z czterech rejestrów są naprawdę potrzebne? Sporo zespołów zaczyna od wszystkich, a potrzebuje statusu VAT i numeru rachunku, czyli jednego API.
3. Czy wynik musi zostawiać dowód? Jeżeli tak, do zakresu wchodzi przechowywanie identyfikatora zapytania, daty i treści odpowiedzi, a nie tylko odczyt.
4. Kto to utrzyma za rok? Odpowiedź „ta sama osoba, która napisała" jest w praktyce najdroższa z możliwych.

Jeżeli po tych czterech pytaniach wychodzi, że chodzi o funkcję pomocniczą, a nie o rdzeń produktu, sensowniej jest wziąć jedną końcówkę, która zwraca komplet danych. Tak działa API do rejestrów w Businesses: jedno uwierzytelnienie, jeden format odpowiedzi dla KRS, CEIDG, rejestru GUS i wykazu VAT, a każde sprawdzenie zapisuje się razem z datą. Dostęp przez API wchodzi od pakietu Firma, a porównanie zakresu pakietów znajdziesz w cenniku.

Najczęstsze pytania przed decyzją

Czy CEIDG API jest darmowe?

Tak. Rejestracja w hurtowni danych CEIDG i Biznes.gov.pl jest bezpłatna, a klucz JWT przychodzi mailem w kilka minut od zgłoszenia. Opłat za zapytania nie ma. Koszt integracji to wyłącznie czas pracy zespołu po Twojej stronie i późniejsze utrzymanie, które wraca przy każdej zmianie wersji API.

Czym różni się API REGON od API CEIDG?

Zakresem i technologią. CEIDG obejmuje jednoosobowe działalności i działa po REST z tokenem JWT. REGON obejmuje wszystkie podmioty gospodarki narodowej, także spółki, i działa po SOAP z kluczem użytkownika oraz osobnym kluczem sesji. Do pełnego obrazu firmy zwykle potrzeba obu, a do tego jeszcze KRS i wykazu podatników VAT.

Ile numerów NIP można sprawdzić naraz w API wykazu VAT?

Maksymalnie trzydzieści w jednym zapytaniu wsadowym, i tyle samo dla numerów REGON oraz numerów rachunków bankowych. Każde zapytanie musi zawierać parametr daty, bo wykaz zwraca stan na wskazany dzień. Przy zamknięciu miesiąca w biurze rachunkowym oznacza to kolejkowanie paczek po trzydzieści numerów i pilnowanie, żeby data odpowiadała dniu transakcji, a nie dniu sprawdzenia.

Czy dane z rejestrów można u siebie przechowywać?

Co do zasady tak, bo to dane publiczne, ale każdy rejestr ma własny regulamin dotyczący zakresu i sposobu ponownego wykorzystania, a dane osobowe przedsiębiorców wpisanych do CEIDG podlegają dodatkowym ograniczeniom. Zakres tego, co wolno pokazać i przez jaki czas trzymać, warto ustalić przed wdrożeniem, a nie po pierwszym zapytaniu użytkownika o usunięcie danych.

Co daje identyfikator zapytania z wykazu VAT?

Jest dowodem, że sprawdzenie faktycznie się odbyło i kiedy. Przy sporze z urzędem to on odróżnia udokumentowaną weryfikację od zapewnienia, że „przecież patrzyliśmy". Sam odczyt przez API go zwraca, ale jeżeli integracja go nie zapisze, znika razem z odpowiedzią. Mechanikę sprawdzeń, których dotyczy ten dowód, opisują strony biała lista rachunek bankowy oraz sprawdzenie podatnika VAT.

Co z tego wynika

Darmowe API nie znaczy darmowa integracja. Cztery rejestry to cztery protokoły, cztery sposoby uwierzytelnienia i cztery kolejki zmian, na które nie masz wpływu. Jeżeli dane rejestrowe są rdzeniem Twojego produktu, zbuduj to u siebie i potraktuj jako inwestycję. Jeżeli mają tylko podpowiadać status kontrahenta w systemie, który już masz, policz czas zespołu na dwa lata do przodu i porównaj go z jedną końcówką, która zwraca komplet danych razem z dowodem sprawdzenia.