Jak udostępnić dane katalogu firm w formacie API

Udostępnienie katalogu firm przez API nie polega na wystawieniu całej bazy pod jednym adresem i dodaniu przycisku „pobierz”. Taki skrót zwykle kończy się przeciążonym serwerem, kopiowaniem rekordów przez boty i sporami o to, które dane odbiorca miał prawo wykorzystać. Najpierw trzeba ustalić zakres informacji, zasady ich aktualizacji oraz to, kto i w jakim celu może je pobierać. Dopiero potem wybiera się technologię.

Dobrze zaprojektowane API katalogu firm pozwala partnerom pobierać dane automatycznie, bez eksportowania plików CSV i ręcznego poprawiania rekordów. Może zasilać wyszukiwarki usług, systemy CRM, aplikacje zakupowe, porównywarki, platformy marketplace czy narzędzia do weryfikacji kontrahentów. Jednocześnie tworzy nowy kanał dystrybucji danych, który trzeba monitorować tak samo jak panel administracyjny albo system płatności.

Najpierw ustal, jakie dane API ma rzeczywiście udostępniać

Pierwsza decyzja dotyczy nie formatu odpowiedzi, lecz modelu danych. W katalogu firm zazwyczaj znajdują się:

• nazwa podmiotu lub firmy przedsiębiorcy,
• numer NIP, REGON albo KRS,
• adres siedziby lub miejsca prowadzenia działalności,
• współrzędne geograficzne,
• numery telefonów i adresy e-mail,
• adres strony internetowej,
• godziny otwarcia,
• kategorie działalności,
• opis oferty,
• zdjęcia i logotypy,
• status aktywności wpisu,
• data ostatniej aktualizacji.

Nie wszystkie pola powinny być dostępne każdemu odbiorcy. NIP, REGON i KRS są przydatne do identyfikacji podmiotu, ale prywatny numer telefonu właściciela jednoosobowej działalności nie powinien automatycznie trafiać do każdego klienta API tylko dlatego, że wcześniej znalazł się w publicznym katalogu. Publiczna dostępność informacji nie oznacza nieograniczonego prawa do ich dalszego profilowania, masowego kopiowania lub wykorzystywania w marketingu.

W praktyce najlepiej podzielić dane na trzy warstwy:

• publiczną – podstawowa nazwa, kategoria, miejscowość, adres strony i identyfikator wpisu;
• partnerską – pełny adres, telefon, współrzędne, godziny otwarcia i rozszerzone opisy;
• wewnętrzną – historia zmian, dane moderacyjne, źródło rekordu, zgłoszenia użytkowników i informacje rozliczeniowe.

Taki podział ogranicza skutki błędnej integracji. Partner odpowiedzialny za mapę punktów usługowych nie potrzebuje notatek moderatora ani adresu e-mail osoby, która zgłosiła korektę wpisu.

Każdy rekord powinien mieć stały identyfikator techniczny, niezależny od NIP-u i nazwy firmy. Nazwa może się zmienić, działalność może zostać przekształcona, a kilka oddziałów może działać pod jednym NIP-em. Dobrym rozwiązaniem jest identyfikator UUID, na przykład 7f841c87-09da-4c27-84cb-5098c234e201. Nie warto budować adresów zasobów wyłącznie na nazwach typu /firmy/hydraulik-krakow, ponieważ zmiana nazwy lub kategorii wymusi zmianę adresu i zepsuje integracje klientów.

Trzeba też rozstrzygnąć, co dokładnie oznacza „firma”. Jeden podmiot prawny może mieć 40 placówek, różne godziny pracy, osobne telefony i różne zakresy usług. Dlatego rozsądny model rozdziela co najmniej:

• podmiot,
• markę,
• placówkę,
• kategorię,
• dane kontaktowe.

W przeciwnym razie jeden rekord zacznie zawierać kilka adresów, kilkanaście numerów telefonu i nieczytelną listę godzin otwarcia. Klienci API będą interpretowali te dane na różne sposoby, a błędy pojawią się dopiero po uruchomieniu integracji.

API musi mieć przewidywalne parametry, limity i dokumentację

Dla katalogu firm najczęściej wybiera się REST API zwracające dane w formacie JSON. Jest łatwe do podłączenia w aplikacjach internetowych, systemach CRM i narzędziach analitycznych. GraphQL ma sens, gdy katalog zawiera wiele powiązanych obiektów i odbiorcy potrzebują bardzo różnych zestawów pól. Przy prostym wyszukiwaniu firm REST zwykle jest tańszy w utrzymaniu i łatwiejszy do zabezpieczenia.

Podstawowy zestaw endpointów może wyglądać następująco:

• GET /v1/companies – lista firm,
• GET /v1/companies/{id} – szczegóły firmy,
• GET /v1/locations – lista placówek,
• GET /v1/locations/{id} – szczegóły placówki,
• GET /v1/categories – lista kategorii,
• GET /v1/changes – rekordy zmienione od wskazanego czasu.

Lista firm powinna obsługiwać filtrowanie co najmniej po:

• NIP-ie,
• REGON-ie lub KRS-ie,
• nazwie,
• miejscowości,
• kodzie pocztowym,
• kategorii,
• statusie wpisu,
• dacie aktualizacji.

Przykładowe zapytanie może mieć postać:

GET /v1/companies?city=Gdansk&category=serwis-rowerowy&updated_since=2026-07-01T00:00:00Z&page=1&limit=50

Odpowiedź powinna jednoznacznie wskazywać liczbę wyników, numer strony, limit oraz możliwość pobrania kolejnej partii. Przy mniejszych zbiorach wystarczy paginacja stronicowa. Gdy katalog ma setki tysięcy rekordów i jest często aktualizowany, lepiej zastosować paginację opartą na kursorze. Strony potrafią wtedy „przesuwać się” między zapytaniami: rekord dodany na początku listy powoduje, że klient pobiera część danych ponownie albo pomija jeden wpis.

Rozsądny limit pojedynczej odpowiedzi to zwykle 50–200 rekordów. Zwracanie 10 tys. firm w jednym żądaniu obciąża bazę, zwiększa czas odpowiedzi i utrudnia ponowienie transferu po zerwaniu połączenia. Do eksportu całego katalogu lepiej przygotować osobny mechanizm: okresowy plik, zadanie asynchroniczne albo endpoint zmian przyrostowych.

Istotne parametry operacyjne trzeba opisać liczbowo. Przykładowy poziom startowy dla API obsługującego partnerów biznesowych to:

• do 60–120 zapytań na minutę dla podstawowego klucza,
• do 500–1000 zapytań na minutę dla płatnych integracji,
• czas odpowiedzi poniżej 300–500 ms dla prostego odczytu z pamięci podręcznej,
• dostępność miesięczna na poziomie 99,5–99,9%,
• przechowywanie logów technicznych przez 30–90 dni,
• ostrzeżenie o wycofaniu wersji API z wyprzedzeniem co najmniej 3–6 miesięcy.

Nie są to uniwersalne normy. Limity trzeba dobrać do wielkości bazy, infrastruktury i sposobu korzystania z danych. Katalog zawierający 20 tys. placówek lokalnych będzie miał inne wymagania niż platforma z kilkoma milionami rekordów aktualizowanych codziennie.

Każde przekroczenie limitu powinno zwracać kod HTTP 429 Too Many Requests oraz informację, kiedy klient może ponowić żądanie. Brak czytelnego komunikatu powoduje, że integrator zaczyna automatycznie ponawiać zapytania co kilka sekund, czyli jeszcze bardziej przeciąża usługę.

Dokumentację najlepiej publikować w standardzie OpenAPI 3.x, na przykład przez Swagger UI lub Redoc. Powinna zawierać nie tylko listę endpointów, ale również:

• kompletne przykłady odpowiedzi,
• format dat i strefę czasową,
• zasady paginacji,
• znaczenie wartości pustych,
• możliwe kody błędów,
• limity zapytań,
• sposób uwierzytelniania,
• historię zmian wersji,
• środowisko testowe.

Najbardziej irytującym błędem w dokumentacjach API katalogów jest pokazanie wyłącznie idealnej odpowiedzi 200 OK. Integrator musi również wiedzieć, czym różni się firma nieaktywna od usuniętej, jak wygląda brak numeru telefonu i czy pusta tablica adresów oznacza brak danych, czy błąd synchronizacji.

Kontrola dostępu, aktualizacja danych i odpowiedzialność za ich użycie

Publiczny katalog nie musi mieć całkowicie otwartego API. Nawet gdy pojedyncze wizytówki można oglądać bez logowania, masowe pobieranie danych powinno wymagać identyfikacji klienta. Najprostszy mechanizm to klucz API przekazywany w nagłówku, na przykład X-API-Key. Dla systemów obsługujących dane wrażliwsze lub pozwalających modyfikować rekordy lepszym wyborem jest OAuth 2.0 z krótkotrwałymi tokenami.

Klucza nie należy umieszczać w adresie URL. Adresy trafiają do historii przeglądarek, logów serwerów, narzędzi analitycznych i systemów monitoringu. Wyciek klucza z parametru ?api_key= jest znacznie łatwiejszy niż z nagłówka żądania.

Każdy klient powinien mieć osobne poświadczenia. Jeden wspólny klucz przekazany wszystkim partnerom uniemożliwia ustalenie, kto przeciążył usługę albo pobierał dane niezgodnie z umową. Nie da się też odłączyć jednego odbiorcy bez blokowania pozostałych.

Przed uruchomieniem API trzeba ustalić podstawę prawną udostępniania poszczególnych pól. Szczególnej uwagi wymagają wpisy dotyczące jednoosobowych działalności gospodarczych, ponieważ nazwa firmy często zawiera imię i nazwisko konkretnej osoby. Dane kontaktowe, lokalizacja działalności prowadzonej w mieszkaniu oraz historia zmian mogą pozwalać na bezpośrednią identyfikację właściciela.

Minimalny zestaw działań organizacyjnych obejmuje:

• sporządzenie rejestru udostępnianych pól,
• określenie celu i podstawy ich przetwarzania,
• ustalenie czasu przechowywania danych,
• przygotowanie procedury korekty i usuwania wpisów,
• rejestrowanie dostępu klientów API,
• zawarcie odpowiednich umów z odbiorcami danych,
• ograniczenie eksportu danych, które nie są potrzebne do deklarowanego celu.

Regulamin API powinien jasno określać, czy odbiorca może tworzyć własną kopię katalogu, publikować dane dalej, prowadzić marketing, wzbogacać rekordy z innych źródeł albo przechowywać nieaktualne informacje. Sam zapis „dane można wykorzystywać zgodnie z prawem” jest zbyt ogólny. Nie rozstrzyga żadnego realnego sporu.

Równie ważna jest aktualizacja. Katalog firm szybko traci wartość, jeśli pokazuje zamknięte lokale, stare numery telefonu i błędne godziny pracy. Każdy rekord powinien mieć pola created_at, updated_at i — gdy to potrzebne — deleted_at. Klient może wtedy pobierać tylko zmiany od ostatniej synchronizacji, zamiast codziennie kopiować całą bazę.

Usunięcie rekordu również musi być przekazywane przez API. Najczęściej stosuje się status deleted, znacznik czasu albo osobny strumień zmian. Fizyczne usunięcie wiersza bez pozostawienia informacji sprawia, że partner nadal przechowuje dawną wersję wpisu i nie wie, że powinien ją wycofać.

W przypadku katalogów lokalnych warto rozdzielić dane pochodzące z rejestrów publicznych od informacji dostarczanych przez przedsiębiorców i użytkowników. Źródło powinno być zapisane technicznie, na przykład jako source=CEIDG, source=KRS, source=owner albo source=editorial. Dzięki temu można ustalić, czy zmiana nazwy pochodzi z oficjalnego rejestru, czy z formularza przesłanego przez anonimowego użytkownika.

Najlepsza technologia nie naprawi złych danych. Duplikaty, różne formaty numerów telefonu, pomylone współrzędne i kategorie tworzone bez słownika wyjdą na jaw natychmiast po udostępnieniu API. Przed publikacją trzeba ujednolicić co najmniej format NIP-u, kodów pocztowych, numerów telefonów, dat oraz identyfikatorów kategorii.

Dobrą praktyką jest udostępnienie najpierw wersji pilotażowej dwóm lub trzem partnerom. Przez cztery–sześć tygodni można wtedy sprawdzić rzeczywiste obciążenie, niezrozumiałe pola, błędy paginacji i zakres danych, którego integratorzy faktycznie potrzebują. Dopiero po tym etapie warto ustalać płatne pakiety.

Orientacyjny koszt przygotowania prostego API nad uporządkowaną bazą zaczyna się zwykle od 15–30 tys. zł netto. Projekt obejmujący przebudowę modelu danych, panel do zarządzania kluczami, rozliczanie użycia, dokumentację, testy bezpieczeństwa i monitoring częściej mieści się w przedziale 50–150 tys. zł netto. Najdroższe nie jest napisanie endpointu. Koszt rośnie przez porządkowanie danych, obsługę wyjątków i utrzymanie zgodności kolejnych wersji.

Model płatności może opierać się na miesięcznym abonamencie, liczbie żądań lub liczbie pobranych rekordów. Na początku lepiej rozliczać dostęp według prostych pakietów niż próbować wyceniać każde pole. Skomplikowany cennik utrudnia sprzedaż i generuje spory o to, czy zapytanie zakończone pustym wynikiem powinno być płatne.

Więcej informacji na: wizytówki NAP – naphub.pl.

FAQ

Czy API katalogu firm musi być płatne?
Nie. Bezpłatny dostęp ma sens dla niewielkiej liczby zapytań, projektów społecznych albo integracji zwiększających zasięg katalogu. Płatny pakiet powinien pojawić się wtedy, gdy odbiorca potrzebuje wyższych limitów, pełnych danych, gwarantowanej dostępności lub wsparcia technicznego.

Czy można udostępnić przez API wszystkie dane widoczne na stronie katalogu?
Nie należy przyjmować takiej zasady automatycznie. Widok pojedynczej wizytówki i masowy eksport całego zbioru mają inne skutki. Przed publikacją trzeba ocenić każde pole, szczególnie dane jednoosobowych działalności, prywatne telefony, adresy e-mail i lokalizacje domowe.

Jak często aktualizować dane?
Dane krytyczne, takie jak status działalności, adres i numer telefonu, najlepiej synchronizować codziennie lub po otrzymaniu zmiany. Opisy, zdjęcia i kategorie mogą być aktualizowane rzadziej. API powinno zawsze zwracać datę ostatniej modyfikacji rekordu.

Czy lepiej udostępnić REST API, czy pliki CSV?
REST API jest lepsze do wyszukiwania pojedynczych firm i regularnego pobierania zmian. Pliki CSV lub JSON Lines sprawdzają się przy pełnym eksporcie dużej bazy. W rozbudowanym katalogu często potrzebne są oba mechanizmy.

Czy API powinno umożliwiać edycję firm?
Na pierwszym etapie nie. Odczyt jest prostszy do zabezpieczenia i przetestowania. Zapisywanie zmian wymaga uprawnień, walidacji, moderacji, historii wersji oraz procedury rozstrzygania konfliktów. Endpointy zapisu warto dodać dopiero po ustabilizowaniu modelu odczytu.

Co zrobić, gdy firma zostanie usunięta z katalogu?
API powinno przekazać informację o usunięciu wraz z identyfikatorem i datą zmiany. Samo zniknięcie rekordu z listy nie wystarcza, ponieważ odbiorcy nie wiedzą, czy wpis został usunięty, czy tylko nie znalazł się na aktualnej stronie wyników.

Czy potrzebne są osobne wersje API?
Tak, gdy zmiana może zepsuć działające integracje. Usunięcie pola, zmiana jego typu albo przebudowa struktury odpowiedzi powinna prowadzić do nowej wersji, na przykład /v2/. Dodanie opcjonalnego pola zwykle nie wymaga nowej wersji.

Prace należy zacząć od inwentaryzacji pól i usunięcia duplikatów, a nie od wyboru frameworka. Najpierw wybierz 20–30 najważniejszych rekordów, porównaj je z CEIDG, KRS lub REGON, sprawdź adresy, identyfikatory i status działalności, a następnie zapisz docelową strukturę jednego poprawnego obiektu JSON. Jeżeli na tym etapie nie da się jednoznacznie opisać firmy, placówki i źródła danych, publikowanie API trzeba odłożyć. Wystawienie nieuporządkowanej bazy tylko szybciej rozprowadzi jej błędy.