Narzędzia i bezpieczeństwo

API dla początkujących: co to jest? i o co zapytać dostawcę systemu

Nie musisz umieć programować, żeby podjąć dobrą decyzję o API. Musisz wiedzieć, o co zapytać przed zakupem systemu, czym jest klucz, skąd biorą się limity zapytań i co znaczy webhook. Poniżej to wszystko po ludzku, razem z tabelą pytań do dostawcy i z tym, co robić, gdy API nie ma wcale.

8 minut czytania

4 częścityle ma każde zapytanie do API: adres, metoda, nagłówki z kluczem i opcjonalne dane
100 do 150zapytań na 10 sekund dopuszcza HubSpot dla aplikacji prywatnych, zależnie od planu; własny limit ma każde API
6 pytańtyle wystarczy zadać dostawcy systemu, żeby wiedzieć, czy da się go spiąć z resztą firmy
2500 zł nettotydzień warsztatu, na którym sprawdzamy dokumentację Twoich systemów i spisujemy, co realnie udostępniają

Krótka odpowiedź

Co to jest API i dlaczego pytasz o nie przed zakupem systemu?

API to sposób, w jaki jeden program prosi drugi o dane albo zleca mu operację, bez człowieka klikającego w ekran. Tyle. Reszta to szczegóły techniczne, których nie musisz znać, żeby podjąć decyzję zakupową.

Dla Ciebie znaczy to jedno: system z działającym API da się połączyć z resztą firmy, a system bez niego zostaje wyspą, z której ktoś przepisuje dane ręcznie. Ta praca nie znika sama, tylko rośnie razem z liczbą klientów i faktur.

Zapytaj dostawcę o cztery rzeczy, zanim podpiszesz umowę: czy API jest w Twoim planie cenowym, gdzie leży jego publiczna dokumentacja, jakie ma limity zapytań i czy da się przez nie pobrać te konkretne pola, o które Ci chodzi. Odpowiedzi weź na piśmie.

Co to jest API i z czego składa się jedno zapytanie?

Definicja w jednym zdaniu: API to zestaw reguł, według których jeden program pyta drugi o dane albo zleca mu operację i dostaje odpowiedź w formacie czytelnym dla maszyny. Nie ma tu magii ani kelnera.

Najczęstszy typ nazywa się REST API. Działa po tym samym protokole co strony internetowe, a odpowiedź zwraca w formacie JSON, czyli w tekście, który przeczyta zarówno program, jak i człowiek. Jedno zapytanie ma zawsze te same cztery części.

Adres, czyli endpoint: dokładne miejsce, do którego pukasz, na przykład lista kontaktów w CRM
Metoda: GET pobiera dane, POST tworzy nowy rekord, PUT albo PATCH aktualizuje istniejący, DELETE usuwa
Nagłówki: między innymi klucz albo token, po którym system rozpoznaje, kto pyta i co mu wolno
Dane: przy tworzeniu i aktualizacji dokładasz treść rekordu, przy zwykłym pobieraniu nie ma jej wcale

Co znaczy, że system „ma API”, i dlaczego to pierwsze pytanie przy zakupie?

„Mamy API” w materiałach sprzedażowych znaczy tylko tyle, że producent taki interfejs zbudował. Nie znaczy, że masz do niego dostęp w swoim planie, że jest udokumentowany i że obejmuje moduł, który Cię interesuje. To trzy różne rzeczy i sprawdza się je osobno.

Sprawdzić możesz sam, w pięć minut. Wpisz w wyszukiwarkę nazwę systemu i słowo „developers” albo „API docs”. Publiczna dokumentacja z listą adresów i przykładami zapytań to dobry znak. Jeśli jedyne, co znajdziesz, to formularz „skontaktuj się z działem handlowym”, potraktuj to jako odpowiedź.

Pytanie zadaj przed zakupem, nie po roku. Po roku masz w tym systemie dane, historię i koszt wyjścia, więc rozmawiasz z pozycji kogoś, kto nie może odejść. Jak porównywać narzędzia pod tym kątem, rozpisaliśmy w poradniku jak wybrać platformę automatyzacji.

Dlaczego klucz API traktujesz jak hasło, a nie jak ustawienie?

Klucz API to ciąg znaków, który leci razem z zapytaniem i po którym system rozpoznaje, kto pyta. Kto ma klucz, ten dla systemu jest Tobą, z Twoimi uprawnieniami. Nie ma tu drugiego składnika, kodu z SMS-a ani pytania „czy to na pewno Ty”.

Dlatego klucz wklejony do arkusza, wysłany na Slacku albo zapisany w opisie zadania jest tym samym co hasło administratora zostawione na kartce przy monitorze. Gdy przez to API przechodzą dane osobowe klientów, wyciek klucza jest incydentem w rozumieniu RODO, a nie usterką narzędzia.

Osobny klucz dla każdej integracji, żeby dało się odebrać jeden dostęp bez wyłączania pozostałych
Najwęższe możliwe uprawnienia: jeśli integracja tylko czyta faktury, nie dawaj jej prawa zapisu
Klucz w menedżerze haseł albo w sejfie sekretów platformy, nigdy w arkuszu i nigdy w mailu
Zapisana data wygaśnięcia i przypomnienie 7 dni wcześniej, bo klucze wygasają zwykle w weekend
Lista, kto i po co ma dostęp; przy odejściu osoby z firmy klucze przechodzą tę samą drogę co karty do biura

Ile zapytań mieści się w limicie i co się dzieje po jego przekroczeniu?

Każdy dostawca ogranicza liczbę zapytań w oknie czasowym, żeby jeden klient nie położył systemu wszystkim pozostałym. HubSpot dopuszcza dla aplikacji prywatnych 100 do 150 zapytań na 10 sekund, zależnie od planu, i podaje to w dokumentacji dla programistów. Inni dostawcy trzymają swoje liczby w tym samym miejscu.

Po przekroczeniu limitu API nie zwraca danych, tylko komunikat o odrzuceniu, zwykle na kilka minut albo na godzinę. Dobrze napisana integracja to przewiduje: zwalnia tempo, ponawia próbę i wraca po dane, których nie dostała. Źle napisana gubi ten fragment po cichu, a brak wychodzi dopiero wtedy, gdy nie zgadza się raport.

Limit liczy się zwykle na całe konto, więc dzielą go między siebie wszystkie Twoje integracje naraz
Operacje masowe rób wsadami: jedno zapytanie na 100 rekordów zamiast 100 osobnych wywołań
Pierwsze pobranie historii jest najcięższe, więc planuje się je na noc i pobiera stronami

Czym webhook różni się od odpytywania co minutę?

Odpytywanie polega na tym, że Twoja automatyzacja co jakiś czas pyta system: „czy jest coś nowego”. Webhook odwraca kierunek, bo to system sam wysyła powiadomienie w chwili, gdy coś się wydarzy. Zamiast pukać do drzwi co minutę, zostawiasz numer i czekasz na telefon.

Różnica jest w opóźnieniu i w zużyciu limitu. Odpytywanie co 15 minut oznacza kwadrans opóźnienia w najgorszym przypadku i kilkaset pustych zapytań dziennie. Webhook daje reakcję w sekundach i nie zjada limitu, ale wymaga adresu, pod który dostawca wyśle powiadomienie, oraz planu na sytuację, w której powiadomienie nie dojdzie.

Kryterium	Odpytywanie co X minut	Webhook
Opóźnienie reakcji	tyle, co odstęp między pytaniami, zwykle 5 do 60 minut	sekundy od zdarzenia
Zużycie limitu	zapytania lecą także wtedy, gdy nic się nie zmieniło	ruch tylko wtedy, gdy coś się wydarzyło
Co musisz mieć	klucz i harmonogram uruchomień	publiczny adres odbiorczy i weryfikację podpisu
Awaria po drugiej stronie	kolejne pytanie dociągnie zaległości samo	powiadomienie może przepaść, więc potrzebna kontrola raz na dobę
Kiedy to wybieramy	raporty, synchronizacja nocna, systemy bez webhooków	nowe zamówienie, nowy lead, zmiana statusu płatności

W praktyce łączy się oba: webhook do reakcji na zdarzenia i odpytywanie raz na dobę jako kontrola, czy nic nie przepadło. Jedno i drugie ustawisz bez pisania kodu w Make, n8n albo Zapier, wypełniając formularz z adresem i parametrami.

Co zrobić, gdy „mamy API” nie znaczy „da się pobrać to pole”?

Interfejs pokazuje tylko to, co producent zdecydował się w nim wystawić. Bywa, że w panelu widzisz numer umowy albo notatkę handlowca, a w API tego pola nie ma. Bywa też, że jest, ale wyłącznie do odczytu, więc zapisu z drugiej strony nie zrobisz. To normalna sytuacja i sprawdza się ją przed wyceną, nie po niej.

Kolejność sprawdzania jest zawsze taka sama i mieści się w jednym dniu pracy.

Nazwij pola, nie system
Wypisz konkretnie, co ma przechodzić: numer zamówienia, NIP, kwota netto, status płatności, data wysyłki. „Integracja z ERP” nie jest wymaganiem, tylko nazwą katalogu.
Znajdź te pola w dokumentacji
Otwórz dokumentację API i sprawdź, czy każde z nich w niej występuje i w którą stronę działa. Pole, którego nie ma, zapisz osobno razem z pytaniem do dostawcy.
Zapytaj o drogę zapasową
Gdy pola nie ma w API, pytaj o eksport wsadowy do pliku, o widok w bazie tylko do odczytu albo o webhook dopisany po stronie dostawcy. Zwykle któraś z tych dróg istnieje.
Ustal eksport jako minimum
Jeśli żadna droga nie istnieje, zostaje minimum: cykliczny eksport całości danych do pliku CSV albo XML, o który nie musisz nikogo prosić. To jest też Twoje wyjście z systemu przy zmianie dostawcy.

O co zapytać dostawcę systemu, zanim go kupisz?

Sześć pytań, które mieszczą się w jednym mailu do handlowca. Odpowiedzi poproś na piśmie i dopnij do umowy, bo za rok nikt nie będzie pamiętał, co padło na rozmowie. Te same pytania zadajemy na warsztacie, zanim ktokolwiek napisze pierwszą linię integracji.

Odpowiedź z prawej kolumny nie przesądza, że system odpada. Oznacza tyle, że integracja będzie kosztować więcej i że masz o tym wiedzieć przed podpisem. Jak wygląda taka integracja pisana od zera, opisaliśmy w usłudze integracja systemów przez API, a przykład dobrze udokumentowanego interfejsu znajdziesz na stronie integracja z HubSpot.

Pytanie do dostawcy	Odpowiedź, która wystarcza	Odpowiedź, która oznacza kłopot
Czy API jest w moim planie i czy jest dopłata?	tak, w tym planie, bez dopłaty	„od wyższego planu” albo dodatek liczony od zapytań
Gdzie leży dokumentacja?	publiczny adres, lista endpointów, przykłady	„wyślemy PDF po podpisaniu umowy”
Jakie są limity zapytań?	liczba i okno czasowe podane wprost w dokumentacji	„nie ma limitów” albo „to zależy od obciążenia”
Czy są webhooki i na jakie zdarzenia?	lista zdarzeń i sposób weryfikacji podpisu	„można przecież odpytywać co minutę”
Czy jest środowisko testowe?	osobne konto testowe z własnym kluczem	„testujecie na produkcji, tylko ostrożnie”
Jak wyeksportuję wszystkie dane przy odejściu?	eksport całości do pliku, samodzielnie z panelu	„eksport robimy na zlecenie i jest płatny”

Ostatnie pytanie zadaj nawet wtedy, gdy API wygląda doskonale. To jedyna pozycja z tej listy, na którą poznasz odpowiedź w najgorszym możliwym momencie, jeśli nie zapytasz teraz.

Najczęstsze błędy

Sześć błędów, które kosztują najwięcej przy pierwszym kontakcie z API

Zakup systemu bez sprawdzenia, czy API jest w kupowanym planie
Interfejs istnieje, ale zaczyna się od planu wyżej albo od płatnego dodatku. Dowiadujesz się o tym wtedy, gdy dane są już w środku i wyjście kosztuje.
Jeden klucz API używany przez wszystkie integracje naraz
Odebranie dostępu jednej z nich wyłącza pozostałe. A gdy klucz wycieknie, nie wiadomo, którędy i co zdążyło przez niego przejść.
Klucz trzymany w arkuszu, w mailu albo w treści zadania
Klucz działa jak hasło z pełnymi uprawnieniami. Przy danych osobowych klientów jego wyciek jest incydentem w rozumieniu RODO, a nie usterką narzędzia.
Integracja bez obsługi limitu i bez kolejki błędów
Po odbiciu od limitu brakujące rekordy nie wracają same. Nikt tego nie widzi do dnia, w którym nie zgadza się raport albo faktura.
Wymaganie opisane jako „integracja z ERP”, bez nazwania pól
Wycena rozjeżdża się w połowie prac, gdy okazuje się, że jednego pola API nie wystawia. Termin przesuwa się o tygodnie, a winnego nie ma.
Brak pytania o eksport danych przy wyjściu z systemu
Przy zmianie dostawcy okazuje się, że wyciągnięcie własnych danych jest usługą płatną i trwa tygodnie. Negocjujesz wtedy z bardzo słabej pozycji.

Lista kontrolna

Lista kontrolna przed podpisaniem umowy na nowy system

Jeśli którykolwiek punkt jest na „nie”, wróć z pytaniem do dostawcy, zanim podpiszesz.

Wiesz, czy API jest w Twoim planie cenowym, i masz to na piśmie
Znasz adres publicznej dokumentacji i widziałeś w niej przykładowe zapytanie
Pola, które mają przechodzić między systemami, są wypisane z nazwy, nie jako nazwa systemu
Limit zapytań jest zapisany razem z informacją, czy liczy się na konto, na użytkownika, czy na klucz
Każda integracja ma własny klucz, najwęższe uprawnienia i zapisaną datę wygaśnięcia
Klucze leżą w menedżerze haseł albo w sejfie sekretów, nie w arkuszu i nie w skrzynce mailowej
Wiesz, jak samodzielnie wyeksportujesz całość danych, gdy zmienisz dostawcę
Jest ustalone, kto dostaje powiadomienie w dniu, w którym integracja przestanie działać

Źródła

Sprawdźmy Twoje systemy

Zanim kupisz system, sprawdź, czy da się go spiąć z resztą firmy

Na bezpłatnej konsultacji (30 minut) wystarczy nazwać systemy, które już masz, i te, które rozważasz. Powiemy, czy mają API, czy jest ono w Twoim planie i czy da się przez nie pobrać to, o co Ci chodzi. Warsztat procesowy kosztuje 2500 zł netto za tydzień i kończy się listą pól, limitów i dróg wejścia, którą zrealizuje także Twój własny programista. Wdrożenie wyceniamy po warsztacie.

Umów bezpłatną konsultację

Najczęstsze pytania

Czym jest API w prostych słowach?

To sposób, w jaki jeden program prosi drugi o dane albo zleca mu operację, bez człowieka klikającego w ekran. Zapytanie ma cztery części: adres, metodę (pobierz, utwórz, zaktualizuj, usuń), nagłówki z kluczem oraz opcjonalne dane. Odpowiedź wraca w formacie, który program umie odczytać.

Skąd mam wiedzieć, czy mój system ma API?

Wpisz w wyszukiwarkę nazwę systemu i słowo „developers” albo „API docs”. Publiczna dokumentacja z listą adresów i przykładami zapytań oznacza, że interfejs istnieje i jest opisany. Osobno sprawdź w cenniku, czy dostęp do niego masz w swoim planie, bo to bywa funkcja z wyższego pakietu.

Czy klucz API to to samo co hasło?

W praktyce tak, i to hasło bez drugiego składnika. Kto ma klucz, ten dla systemu jest Tobą, z Twoimi uprawnieniami. Dlatego każda integracja dostaje własny klucz z najwęższymi uprawnieniami, klucze leżą w menedżerze haseł, a data ich wygaśnięcia jest zapisana razem z przypomnieniem 7 dni wcześniej.

Co się stanie, gdy przekroczę limit zapytań?

API przestaje zwracać dane i odpowiada komunikatem o odrzuceniu, zwykle na kilka minut albo na godzinę. Poprawnie napisana integracja zwalnia tempo, ponawia próbę i wraca po brakujące rekordy. Bez tej obsługi dane z odrzuconego okna nie docierają nigdy, a braku nikt nie zauważa do czasu rozbieżności w raporcie.

Czym jest webhook i kiedy użyć go zamiast odpytywania?

Webhook to powiadomienie, które system wysyła sam w chwili zdarzenia, zamiast czekać na Twoje pytanie. Wybierasz go tam, gdzie liczy się czas reakcji: nowe zamówienie, nowy lead, zmiana statusu płatności. Odpytywanie zostaje do raportów i do systemów, które webhooków nie mają, oraz jako kontrola raz na dobę.

Czy da się korzystać z API bez programisty?

Tak, do prostych scenariuszy wystarczą Make, n8n albo Zapier: wypełniasz formularz z adresem, metodą i parametrami, zamiast pisać kod. Zanim zbudujesz automatyzację, warto przetestować samo zapytanie w darmowym narzędziu w rodzaju Postmana. Integracja z limitami, stronicowaniem i kolejką błędów to już praca dla kogoś z doświadczeniem.

Co zrobić, gdy system nie ma API?

Sprawdzasz drogi zapasowe w tej kolejności: eksport wsadowy do pliku, import z pliku, widok w bazie tylko do odczytu, webhook dopisany przez dostawcę. Minimum, którego nie warto odpuszczać, to cykliczny eksport całości danych do CSV albo XML. Jeśli nie ma nawet tego, policz koszt ręcznego przepisywania i wpisz go do decyzji zakupowej.

Ile kosztuje integracja przez API?

Warsztat procesowy kosztuje 2500 zł netto za tydzień i kończy się listą pól, limitów i dróg wejścia. Wdrożenie wyceniamy po warsztacie, bo dopiero wtedy wiadomo, ile systemów wchodzi w grę i czy mają dokumentację. Licencje platformy automatyzacji i koszt modeli AI (od 0,02 do 0,30 zł za zapytanie) płacisz dostawcom bezpośrednio.