API – co to jest i jak działa? Przewodnik dla firm

Czym jest API? Definicja i rozwinięcie skrótu

API to skrót angielskiej nazwy Application Programming Interface. Po polsku mówi się „interfejs programistyczny aplikacji” lub „interfejs programowania aplikacji”. W praktyce API jest umową między dwoma programami: jeden wie, o co i w jakiej formie może zapytać, a drugi – co ma odesłać. Dzięki wspólnym regułom systemy współpracują, choć powstały u różnych producentów i w różnych technologiach.

Dobrym porównaniem jest okienko na poczcie. Nie wchodzisz do sortowni – podajesz przesyłkę z wypełnionym formularzem i dostajesz potwierdzenie nadania z numerem do śledzenia. API działa podobnie: udostępnia ściśle opisane „okienka”, przez które inny program składa zlecenie albo pyta o dane, bez dostępu do bazy danych i kodu drugiego systemu.

Sam termin jest szeroki – własne API ma też system operacyjny czy przeglądarka. Gdy jednak ktoś mówi, że firmowy system „ma API”, prawie zawsze chodzi o web API: interfejs dostępny przez sieć, z którym inne programy komunikują się protokołem HTTP. O nim jest ten poradnik.

Jak działa API? Zapytanie i odpowiedź

Każda wymiana danych przez web API składa się z zapytania (ang. request) i odpowiedzi (ang. response). Program, który pyta, to klient, a system, który odpowiada, to serwer. Klientem może być sklep internetowy, aplikacja mobilna, skrypt uruchamiany co godzinę albo inny serwer. Zapytanie ma cztery podstawowe elementy:

• Endpoint – adres konkretnej funkcji lub zasobu, np. „/zamowienia” albo „/klienci/58”, dopisywany do adresu bazowego API.
• Metoda HTTP – mówi, co zrobić: GET pobiera dane, POST tworzy nowy rekord, PUT zastępuje istniejący w całości, PATCH zmienia jego wybrane pola, a DELETE go usuwa.
• Nagłówki – informacje o samym zapytaniu: klucz API lub token, który potwierdza, kto pyta, oraz format przesyłanych danych, np. „Content-Type: application/json”.
• Treść (ang. body) – dane wysyłane do serwera, najczęściej w formacie JSON (JavaScript Object Notation), w którym zapisuje się je jako pary „nazwa pola: wartość”. Zapytania GET zwykle nie mają treści.

Serwer sprawdza uprawnienia klienta, wykonuje operację i odsyła odpowiedź z nagłówkami, treścią i trzycyfrowym kodem statusu. Kody 2xx oznaczają sukces, 4xx – błąd po stronie klienta (złe dane, brak uprawnień), a 5xx – problem po stronie serwera. Po kodzie program od razu wie, czy przetworzyć wynik, poprawić zapytanie, czy spróbować później.

Ten sam mechanizm działa wewnątrz wielu nowoczesnych aplikacji webowych: ekran w przeglądarce pobiera i zapisuje dane przez API na serwerze. Z tej samej warstwy może później korzystać aplikacja mobilna albo system partnera, bez budowania logiki od nowa.

Wywołania API w praktyce i kody odpowiedzi

Wywołanie API to pojedyncze zapytanie do konkretnego endpointu. Oto trzy przykłady z pracy systemu sprzedaży, opisane bez kodu.

Przykład 1: sprawdzenie statusu zamówienia

Sklep internetowy wysyła do systemu magazynowego wywołanie „GET /zamowienia/1024” z kluczem API w nagłówku. Serwer odpowiada kodem 200 i odsyła dane w formacie JSON, m.in. status „wysłane”, numer przesyłki i datę nadania. Sklep pokazuje te informacje klientowi na jego koncie. Gdyby zamówienia o tym numerze nie było, odpowiedź miałaby kod 404.

Przykład 2: lista zamówień z filtrem

Parametry zapytania dopisuje się do adresu po znaku zapytania. Wywołanie „GET /zamowienia?status=nowe&strona=2” zwraca drugą stronę listy nowych zamówień. API rzadko oddaje tysiące rekordów naraz, dlatego integracja pobiera je porcjami (tzw. paginacja) i musi wiedzieć, kiedy skończyć.

Przykład 3: dodanie klienta do CRM

Formularz na stronie wysyła do CRM wywołanie „POST /klienci” z nazwą firmy, adresem e-mail i telefonem w treści. CRM zapisuje rekord i odpowiada kodem 201 oraz identyfikatorem nowego klienta, potrzebnym przy kolejnych aktualizacjach. Brak wymaganego pola kończy się kodem 400 z opisem błędu. Uwaga na powtórki: gdy połączenie zerwie się w trakcie, ponowne wysłanie zapytania może utworzyć duplikat, więc integracja powinna najpierw sprawdzić, czy klient już istnieje.

Najczęstsze kody odpowiedzi HTTP

Przy kodach 429 i 5xx zapytanie warto powtórzyć, ale z rosnącymi odstępami; w odpowiedzi 429 serwer często podaje w nagłówku Retry-After, ile odczekać. Kody 400, 401, 403 i 404 wymagają poprawki, a ponawianie takiego zapytania bez zmian niczego nie da. Integracja powinna rozróżniać te sytuacje i zapisywać każdy błąd w dzienniku.

Czym jest REST API?

REST API to interfejs zbudowany według stylu architektonicznego REST (ang. Representational State Transfer). Opisał go Roy Fielding, jeden ze współautorów specyfikacji HTTP, w rozprawie doktorskiej z 2000 roku. REST nie jest protokołem ani gotową biblioteką, tylko zbiorem zasad projektowania. Dziś to najczęściej spotykany styl publicznych API. Jego najważniejsze założenia:

• Zasoby pod własnymi adresami – wszystko, czym system zarządza (zamówienia, klienci, faktury), ma swój adres URL, np. „/klienci” dla listy i „/klienci/58” dla jednego klienta.
• Metody HTTP jako czasowniki – adres mówi, czego dotyczy operacja, a metoda, co z tym zrobić: „GET /klienci/58” pobiera dane klienta, a „DELETE /klienci/58” go usuwa.
• Bezstanowość – każde zapytanie niesie wszystko, czego serwer potrzebuje, łącznie z danymi uwierzytelniającymi. Serwer nie pamięta kontekstu między zapytaniami, więc ruch łatwo rozłożyć na kilka maszyn.
• Reprezentacje – klient nie dostaje rekordu prosto z bazy, tylko jego reprezentację, dziś zwykle w formacie JSON, dawniej często w XML.
• Buforowanie – odpowiedź może informować, czy i jak długo wolno ją przechowywać w pamięci podręcznej, co odciąża serwer przy często czytanych danych.

W praktyce niewiele interfejsów spełnia wszystkie warunki z pracy Fieldinga, a nazwa REST API przylgnęła do większości API opartych na HTTP i JSON. Dla firmy ważniejsze od zgodności z teorią są trzy rzeczy: aktualna dokumentacja, środowisko testowe (ang. sandbox) i przewidywalne komunikaty błędów.

Rodzaje API: według dostępu i stylu

Rodzaje API porządkuje się zwykle według dwóch kryteriów. Pierwsze mówi, kto i na jakich warunkach może z interfejsu korzystać, drugie – jak technicznie przebiega komunikacja.

Webhook to w pewnym sensie odwrócone API. Zamiast co kilka minut pytać bramkę płatniczą, czy klient już zapłacił, podajesz jej adres swojego systemu, a ona sama daje znać, gdy płatność zostanie potwierdzona. Twój serwer musi jednak być dostępny z internetu i sprawdzać, kto wysłał powiadomienie. Często łączy się oba podejścia: webhook sygnalizuje zdarzenie, a zapytanie do API pobiera szczegóły i nadrabia zgubione powiadomienia.

API – przykłady z codziennej pracy firmy

Z API korzysta prawie każda firma, która sprzedaje lub obsługuje klientów w internecie – zwykle w tle gotowych narzędzi. Typowe zastosowania:

• Płatności online – sklep przekazuje bramce płatniczej kwotę i numer zamówienia, a po zapłacie dostaje potwierdzenie, najczęściej webhookiem.
• Śledzenie przesyłek – system sprzedaży zamawia kuriera, pobiera etykietę i sprawdza status paczki, który klient widzi na swoim koncie.
• Kursy walut – cennik w kilku walutach korzysta z kursów pobieranych codziennie z publicznego API, np. Narodowego Banku Polskiego.
• Logowanie kontem zewnętrznym – przycisk „Zaloguj się przez Google” opiera się na standardach OAuth 2.0 i OpenID Connect, więc aplikacja potwierdza tożsamość użytkownika, nie widząc jego hasła.
• Mapy – adres z zamówienia zamienia się na współrzędne, a system wylicza dojazd i pokazuje trasę pracownikowi w terenie.
• Kalendarz – rezerwacja wizyty tworzy wydarzenie w kalendarzu pracownika, a zajęte godziny znikają z formularza na stronie.
• Sklep internetowy i CRM – nowe zamówienie zakłada lub aktualizuje kartę klienta, więc handlowiec widzi historię zakupów bez eksportu z panelu sklepu.
• Księgowość – faktury i dane sprzedaży trafiają do programu księgowego bez przepisywania, a informacja o zapłacie wraca do systemu sprzedaży.
• Dane kontrahenta – po wpisaniu numeru NIP formularz sam uzupełnia nazwę i adres firmy z publicznego rejestru.

Z API korzysta też automatyzacja procesów z AI: asystent, który szykuje odpowiedź dla klienta, sprawdza przez nie status zamówienia i termin dostawy, zamiast zgadywać. Na API opiera się również panel klienta B2B: kontrahent sam sprawdza w nim status zleceń i dokumenty, a dane trafiają do panelu z systemów, w których na co dzień pracuje zespół. Szerzej o sprzedaży między firmami piszemy w poradniku o tym, czym jest platforma B2B.

Bezpieczeństwo API: klucze, tokeny i limity

API otwiera dostęp do danych firmy, dlatego jego zabezpieczenia są równie ważne jak hasła do systemów. Nawet jeśli integrację wykonuje zewnętrzny zespół, warto znać podstawowe mechanizmy:

• Klucz API – długi, losowy ciąg znaków identyfikujący aplikację. Traktuj go jak hasło: nie wysyłaj go e-mailem ani komunikatorem, nie wstawiaj tajnych kluczy do kodu widocznego w przeglądarce i używaj osobnych kluczy do testów i do pracy na żywych danych.
• Tokeny OAuth 2.0 – zamiast hasła aplikacja dostaje token o ograniczonym zakresie uprawnień (ang. scope), np. tylko do odczytu kalendarza. Token dostępu zwykle wygasa po krótkim czasie, a użytkownik może cofnąć zgodę bez zmiany hasła.
• HTTPS – szyfrowane połączenie między klientem a serwerem. Bez niego klucz lub token można przechwycić po drodze.
• Limity zapytań – serwer przyjmuje określoną liczbę wywołań na minutę lub godzinę, a nadmiar odrzuca kodem 429. Chroni to przed przeciążeniem i nadużyciami.
• Minimalne uprawnienia – konto integracji dostaje tylko te prawa, których naprawdę używa. Synchronizacja, która czyta zamówienia, nie musi móc usuwać klientów.

Do tego dochodzą zasady organizacyjne: spis wydanych kluczy z informacją, kto i do czego ich używa, unieważnianie kluczy po zakończeniu współpracy z dostawcą lub odejściu pracownika oraz dziennik wywołań, który pozwala ustalić, kto i kiedy zmienił dane.

Kiedy firma potrzebuje integracji przez API?

Integracja przez API ma zwykle sens, gdy te same dane są prowadzone w kilku systemach, a ludzie ręcznie pilnują ich zgodności. Typowe sygnały:

• Ktoś codziennie przepisuje zamówienia, zgłoszenia lub dane klientów z jednego programu do drugiego
• Eksport i import plików CSV stał się stałym punktem tygodnia
• Zdarzają się pomyłki w kwotach, zdublowane karty klientów albo dwa razy sprzedany termin
• Dwa systemy pokazują różne dane i nikt nie wie, który ma rację
• Odpowiedź na pytanie klienta o status wymaga sprawdzenia kilku narzędzi
• Rośnie liczba zamówień, a ręczna obsługa zajmuje zespołowi coraz więcej czasu

Z integracją lepiej poczekać, gdy takich operacji jest kilka w miesiącu, proces dopiero się kształtuje albo jeden z systemów wkrótce zostanie wymieniony. Najpierw sprawdź też gotowe wtyczki i narzędzia do automatyzacji bez programowania (tzw. no-code). Dedykowana integracja ma sens, gdy potrzebujesz własnej logiki, starannej obsługi błędów i pełnej kontroli nad danymi.

Zanim zaczniesz, ustal dla każdego pola, który system jest źródłem prawdy – bez tej decyzji dwa programy prędzej czy później zaczną nawzajem nadpisywać swoje dane. Dobrze widać to na przykładzie uzgadniania rezerwacji z wielu kanałów sprzedaży z systemem hotelowym. Jeśli chcesz, żeby ktoś przeanalizował Twoje systemy i zaprojektował przepływ danych, zobacz, na czym polega integracja systemów i API, a orientacyjny koszt sprawdzisz w kalkulatorze na stronie cennika.

Co zrobić, gdy system nie ma API?

Brak API nie zamyka drogi do integracji, ale każda alternatywa ma swoją cenę. Warto sprawdzić je w tej kolejności:

1. Zapytaj producenta. API bywa dostępne w wyższym pakiecie, jako płatny moduł albo w nowszej wersji programu, tylko nikt go nie reklamuje.
2. Poszukaj powiadomień. Część systemów nie przyjmuje zapytań, ale potrafi wysłać webhook lub e-mail o zdarzeniu, który da się przetworzyć automatycznie.
3. Wykorzystaj eksport plików. Zaplanowany eksport CSV lub XML, odbierany automatycznie, to prosta i stabilna, choć opóźniona forma wymiany danych.
4. Rozważ dostęp do bazy danych. To szybka droga, ale ryzykowna: aktualizacja programu może zmienić strukturę tabel, a zapis z pominięciem logiki systemu łatwo uszkadza dane. Bezpieczniej ograniczyć się do odczytu.
5. Automatyzację interfejsu (RPA) zostaw na koniec. Robot klika w programie jak człowiek, więc każda zmiana wyglądu ekranu może zatrzymać przepływ.

Jeśli żadna z tych dróg nie jest stabilna, rozsądniejsza bywa wymiana programu na taki, który ma udokumentowane API. Koszt ręcznego przepisywania i jego pomyłek wraca co miesiąc, więc warto go porównać z kosztem zmiany systemu.