Co to jest API i do czego służy?

Klient składa zamówienie w sklepie internetowym. Kilka sekund później dane trafiają do systemu magazynowego, operator płatności potwierdza transakcję, program kurierski tworzy przesyłkę, a platforma marketingowa aktualizuje profil kupującego.

Użytkownik widzi jeden proces, ale w jego obsługę może być zaangażowanych kilka niezależnych systemów.

Każdy z nich posiada własną bazę danych, logikę, sposób logowania i zestaw informacji. Aby mogły ze sobą współpracować, potrzebują uzgodnionego sposobu komunikacji.

Taką rolę bardzo często pełni API.

Dzięki API sklep może poprosić inny system o aktualny stan produktu, przesłać nowe zamówienie, pobrać dane klienta albo zlecić utworzenie dokumentu. Nie trzeba ręcznie eksportować pliku, wysyłać go e-mailem i później importować w kolejnym panelu.

API nie jest jednak magicznym połączeniem, które automatycznie rozumie wszystkie procesy firmy. Każdy system może inaczej nazywać produkty, klientów, statusy i dokumenty. Jeden zapisuje cenę brutto, drugi netto. Jeden rozpoznaje produkt po SKU, drugi po własnym identyfikatorze.

Samo techniczne połączenie dwóch aplikacji jest zwykle tylko częścią pracy. Trzeba również określić, jakie dane mają być wymieniane, który system jest ich źródłem, co zrobić w przypadku błędu i jak uniknąć wielokrotnego wykonania tej samej operacji.

W swojej pracy regularnie spotykam integracje opisywane jako „podłączenie API”, chociaż nikt wcześniej nie rozpisał procesu biznesowego. W efekcie dane są przesyłane, ale produkty się duplikują, zamówienia otrzymują niewłaściwe statusy, a stany magazynowe nadpisują się w niekontrolowany sposób.

Dobrze zaprojektowana integracja nie zaczyna się od pierwszego zapytania do API. Zaczyna się od ustalenia, co ma się wydarzyć, kiedy, w którym systemie i na podstawie jakich danych.

Co to jest API?

API to skrót od angielskiego określenia Application Programming Interface, czyli interfejs programistyczny aplikacji.

API określa sposób, w jaki jeden program może komunikować się z innym systemem.

Definiuje między innymi:

• jakie operacje są dostępne,
• pod jaki adres należy wysłać żądanie,
• jakie dane trzeba przekazać,
• w jakim formacie będą zapisane,
• jak potwierdzić uprawnienia,
• jak wygląda odpowiedź,
• jak system informuje o błędach.

Można traktować API jak ustalony język rozmowy pomiędzy aplikacjami.

System nie musi znać wewnętrznej budowy drugiego programu. Korzysta tylko z operacji, które zostały udostępnione przez jego twórców.

Prosty przykład działania API

Sklep internetowy potrzebuje aktualnej informacji o produkcie znajdującym się w systemie magazynowym.

Proces może wyglądać następująco:

1. Sklep wysyła żądanie zawierające identyfikator produktu.
2. API sprawdza, czy sklep posiada uprawnienia.
3. System magazynowy odnajduje produkt.
4. API zwraca nazwę, cenę, stan i inne dostępne informacje.
5. Sklep przetwarza odpowiedź i aktualizuje produkt.

W drugą stronę sklep może przesłać nowe zamówienie.

1. Klient kończy zakup.
2. Sklep przygotowuje dane zamówienia.
3. Wysyła je do API systemu ERP.
4. ERP sprawdza poprawność danych.
5. Tworzy zamówienie i zwraca jego identyfikator.
6. Sklep zapisuje powiązanie pomiędzy oboma systemami.

Użytkownik nie musi wiedzieć, że w tle nastąpiła wymiana kilku komunikatów.

Do czego służy API?

API może udostępniać dane, funkcje albo możliwość wykonywania operacji w innym systemie.

Może służyć między innymi do:

• pobierania produktów,
• aktualizowania cen,
• synchronizowania stanów magazynowych,
• przesyłania zamówień,
• tworzenia klientów,
• generowania przesyłek,
• sprawdzania statusu płatności,
• pobierania dokumentów,
• rezerwowania terminów,
• zarządzania kontami użytkowników,
• pobierania kursów walut,
• łączenia systemów marketingowych,
• automatyzowania procesów biznesowych.

API może być wykorzystywane przez stronę internetową, aplikację mobilną, system wewnętrzny, wtyczkę WordPressa albo narzędzie automatyzujące.

Czym API różni się od zwykłego panelu?

Panel jest interfejsem przygotowanym dla człowieka.

Użytkownik loguje się, klika przyciski, uzupełnia formularze i odczytuje informacje wyświetlane na ekranie.

API jest interfejsem przygotowanym przede wszystkim dla programów.

Zamiast klikania system wysyła uporządkowane żądania i odbiera odpowiedzi możliwe do automatycznego przetworzenia.

Ta sama operacja może być dostępna zarówno w panelu, jak i przez API.

Pracownik może ręcznie utworzyć przesyłkę w panelu kuriera. Sklep może wykonać podobną operację automatycznie przez API po otrzymaniu zamówienia.

API a dostęp do bazy danych

API i bezpośredni dostęp do bazy danych nie są tym samym.

Bezpośrednie połączenie z bazą pozwala odczytywać lub modyfikować jej tabele. Może być szybkie, ale wymaga znajomości wewnętrznej struktury systemu.

API udostępnia kontrolowane operacje przygotowane przez twórcę aplikacji.

Przykładowo polecenie utworzenia zamówienia przez API może automatycznie:

• sprawdzić poprawność produktów,
• obliczyć podatki,
• zarezerwować stan,
• utworzyć historię zmian,
• uruchomić powiadomienia,
• zastosować reguły biznesowe.

Ręczne dodanie rekordu do tabeli może pominąć te działania i uszkodzić spójność systemu.

Bezpośredni dostęp do bazy bywa potrzebny w migracjach, raportach i kontrolowanych integracjach wewnętrznych. Nie powinien jednak automatycznie zastępować oficjalnego API.

Czym jest endpoint?

Endpoint jest konkretnym adresem lub punktem API obsługującym określoną operację albo rodzaj danych.

Osobne endpointy mogą odpowiadać za:

• listę produktów,
• pojedynczy produkt,
• tworzenie zamówienia,
• aktualizację klienta,
• sprawdzanie płatności,
• pobieranie dokumentu.

Adres endpointu nie zawsze określa całą operację. Znaczenie ma również metoda żądania i przekazane dane.

Co to jest żądanie API?

Żądanie jest komunikatem wysyłanym do API.

Może zawierać:

• adres endpointu,
• metodę,
• nagłówki,
• dane uwierzytelniające,
• parametry zapytania,
• treść z danymi,
• informacje o oczekiwanym formacie odpowiedzi.

Żądanie może na przykład oznaczać:

• pobierz produkt o wskazanym ID,
• utwórz nowe zamówienie,
• zmień status istniejącego zamówienia,
• usuń wskazany rekord,
• zwróć listę produktów zmienionych od określonej daty.

Co to jest odpowiedź API?

Odpowiedź jest komunikatem zwracanym po obsłużeniu żądania.

Może zawierać:

• kod statusu,
• dane wyniku,
• identyfikator utworzonego obiektu,
• komunikat błędu,
• informację o ograniczeniach,
• dodatkowe dane techniczne.

Po utworzeniu zamówienia odpowiedź może zwrócić:

• informację o powodzeniu,
• numer zamówienia w systemie docelowym,
• datę utworzenia,
• aktualny status.

W przypadku błędu powinna wskazać jego rodzaj, na przykład brak produktu, nieprawidłową wartość albo brak uprawnień.

Jakie metody wykorzystuje API?

W API opartym na protokole HTTP często wykorzystuje się kilka podstawowych metod.

GET

GET służy najczęściej do pobierania danych.

Może pobierać:

• pojedynczy produkt,
• listę zamówień,
• status płatności,
• dane klienta.

POST

POST jest często używany do tworzenia nowych danych albo uruchamiania operacji.

Może odpowiadać za:

• utworzenie zamówienia,
• dodanie klienta,
• wysłanie formularza,
• utworzenie przesyłki.

PUT

PUT może służyć do pełnego zastąpienia albo aktualizacji istniejącego obiektu.

PATCH

PATCH jest często używany do częściowej aktualizacji, na przykład zmiany samego statusu albo numeru telefonu.

DELETE

DELETE może służyć do usuwania danych, jeżeli API udostępnia taką możliwość.

Dokładne znaczenie każdej metody zależy od dokumentacji konkretnego API.

Czym jest REST API?

REST API jest popularnym sposobem projektowania komunikacji przez HTTP.

Zasoby są zwykle reprezentowane przez adresy, a operacje wykonywane za pomocą metod takich jak GET, POST, PATCH i DELETE.

REST API często wykorzystuje format JSON.

Jego popularność wynika między innymi z:

• stosunkowo prostej struktury,
• wykorzystania standardów internetowych,
• łatwej obsługi w wielu językach programowania,
• czytelnego podziału zasobów,
• szerokiego wsparcia narzędzi.

Nie każde API nazywane REST spełnia wszystkie założenia tego stylu. W praktyce określenie jest często używane dla interfejsów działających przez HTTP i zwracających JSON.

Czym jest SOAP API?

SOAP jest standardem komunikacji opartym zwykle na dokumentach XML i dokładnie określonych kontraktach.

Może występować w:

• starszych systemach ERP,
• bankowości,
• rozbudowanych systemach korporacyjnych,
• integracjach wymagających ścisłego kontraktu.

SOAP może oferować rozbudowane standardy bezpieczeństwa i formalny opis operacji, ale bywa bardziej złożony we wdrożeniu niż typowe REST API.

Nie należy odrzucać go wyłącznie dlatego, że jest starszą technologią. Jeżeli system udostępnia stabilne SOAP API, integrację należy przygotować zgodnie z jego wymaganiami.

Czym jest GraphQL?

GraphQL pozwala klientowi określić, jakich danych potrzebuje.

Zamiast pobierać cały z góry ustalony zestaw pól, aplikacja może poprosić tylko o wybrane informacje.

Może to ograniczyć:

• pobieranie niepotrzebnych danych,
• liczbę osobnych żądań,
• konieczność tworzenia wielu podobnych endpointów.

GraphQL daje dużą elastyczność, ale wymaga kontroli złożoności zapytań, uprawnień, cache i wydajności.

Nie jest automatycznie lepsze od REST. Wybór zależy od sposobu korzystania z danych i możliwości konkretnego systemu.

W jakim formacie API przesyła dane?

Najczęściej spotykane formaty to:

• JSON,
• XML,
• pliki tekstowe,
• dane formularza,
• pliki binarne.

JSON

JSON jest czytelnym i powszechnie obsługiwanym formatem przedstawiania uporządkowanych danych.

Dobrze nadaje się do opisywania:

• produktów,
• zamówień,
• klientów,
• list obiektów,
• zagnieżdżonych informacji.

XML

XML jest szeroko stosowany w starszych i bardziej formalnych integracjach. Może zawierać rozbudowaną strukturę i przestrzenie nazw.

Pliki

API może również umożliwiać pobieranie lub wysyłanie:

• faktur,
• etykiet kurierskich,
• zdjęć,
• raportów,
• dokumentów PDF.

Czym jest dokumentacja API?

Dokumentacja API opisuje sposób korzystania z interfejsu.

Powinna zawierać między innymi:

• adres bazowy,
• dostępne endpointy,
• metody,
• wymagane parametry,
• format danych,
• sposób uwierzytelniania,
• przykładowe żądania,
• przykładowe odpowiedzi,
• kody błędów,
• limity,
• informacje o wersjach.

Dobra dokumentacja nie ogranicza się do listy adresów. Powinna również wyjaśniać zależności i reguły biznesowe.

Przykładowo utworzenie zamówienia może wymagać wcześniejszego utworzenia klienta albo użycia istniejącego identyfikatora magazynu.

Co zrobić, gdy dokumentacja API jest niepełna?

Braki w dokumentacji znacząco zwiększają czas i ryzyko integracji.

Przed rozpoczęciem prac warto uzyskać odpowiedzi na pytania:

• które środowisko jest testowe,
• jak otrzymać dane dostępowe,
• jakie pola są obowiązkowe,
• który system nadaje identyfikatory,
• jak obsługiwane są błędy,
• jakie obowiązują limity,
• czy dostępny jest webhook,
• jak wygląda wersjonowanie.

Jeżeli dokumentacja nie opisuje danego zachowania, nie zakładam go na podstawie domysłów. Testuję odpowiedź albo uzyskuję potwierdzenie od dostawcy systemu.

Czym jest uwierzytelnianie API?

Uwierzytelnianie pozwala systemowi rozpoznać, kto wysyła żądanie.

Może wykorzystywać:

• klucz API,
• login i hasło techniczne,
• token dostępu,
• OAuth,
• certyfikat,
• podpis kryptograficzny,
• kombinację kilku metod.

Dane dostępowe nie powinny znajdować się w publicznie widocznym kodzie strony.

Jeżeli sekret zostanie umieszczony w JavaScript działającym w przeglądarce, użytkownik może go odczytać.

Operacje wymagające poufnego klucza powinny być wykonywane po stronie serwera albo przez bezpieczną warstwę pośrednią.

Czym jest klucz API?

Klucz API jest ciągiem znaków identyfikującym aplikację lub integrację.

Może być przekazywany w:

• nagłówku żądania,
• parametrze,
• innym miejscu wskazanym przez dokumentację.

Klucz powinien być:

• przechowywany bezpiecznie,
• udostępniany tylko potrzebnym systemom,
• możliwy do unieważnienia,
• regularnie kontrolowany,
• oddzielny dla różnych środowisk.

Nie należy przesyłać klucza w wiadomościach i dokumentach dostępnych dla przypadkowych osób.

Czym jest token dostępu?

Token jest poświadczeniem pozwalającym wykonać określone operacje.

Może posiadać:

• określony czas ważności,
• zakres uprawnień,
• powiązanie z użytkownikiem,
• możliwość odnowienia.

Token krótkoterminowy ogranicza skutki przejęcia danych dostępowych. Po wygaśnięciu przestaje działać.

Integracja musi jednak obsługiwać jego odnawianie i reagować na utratę ważności.

Czym jest OAuth?

OAuth pozwala aplikacji otrzymać ograniczony dostęp do innego systemu bez przekazywania jej głównego hasła użytkownika.

Użytkownik może zostać przekierowany do systemu, zalogować się i zaakceptować określony zakres dostępu.

Aplikacja otrzymuje token, który może pozwalać na przykład na:

• odczyt produktów,
• zarządzanie zamówieniami,
• dostęp do kalendarza,
• odczyt wybranych danych konta.

Użytkownik może później odebrać aplikacji dostęp bez zmiany głównego hasła.

Uwierzytelnianie a autoryzacja

Uwierzytelnianie odpowiada na pytanie:

Kto wysyła żądanie?

Autoryzacja odpowiada na pytanie:

Co ta osoba lub aplikacja może zrobić?

System może rozpoznać integrację, ale pozwolić jej tylko na odczyt produktów bez możliwości ich usuwania.

Uprawnienia powinny być możliwie ograniczone do rzeczywistych potrzeb.

Integracja pobierająca stany magazynowe nie potrzebuje prawa do usuwania klientów i dokumentów.

Czym jest zasada najmniejszych uprawnień?

Zasada najmniejszych uprawnień oznacza nadawanie wyłącznie dostępu niezbędnego do wykonania danego zadania.

Pomaga ograniczyć skutki:

• błędu integracji,
• przejęcia klucza,
• nieprawidłowej konfiguracji,
• działania nieuprawnionej osoby.

Oddzielne klucze warto tworzyć dla:

• środowiska produkcyjnego,
• środowiska testowego,
• różnych integracji,
• zewnętrznych wykonawców.

Dzięki temu można unieważnić jeden dostęp bez zatrzymywania wszystkich połączeń.

Czym są limity API?

API może ograniczać liczbę żądań możliwych do wykonania w określonym czasie.

Limity chronią system przed:

• przeciążeniem,
• błędną pętlą,
• nadużyciem,
• atakami,
• nierównym wykorzystaniem zasobów.

Limit może dotyczyć:

• liczby żądań na sekundę,
• liczby operacji na minutę,
• liczby rekordów dziennie,
• konkretnego konta,
• adresu IP,
• wybranego endpointu.

Po przekroczeniu limitu API może zwrócić błąd i informację, kiedy można ponowić próbę.

Jak obsługiwać limity API?

Integracja nie powinna wysyłać tego samego żądania w niekontrolowanej pętli.

Powinna:

• rozpoznawać odpowiedź o przekroczeniu limitu,
• odczekać określony czas,
• ponowić próbę z opóźnieniem,
• ograniczyć równoległe operacje,
• zapisywać postęp,
• korzystać z operacji zbiorczych, jeżeli są dostępne.

Przy dużym katalogu lepiej pobierać tylko dane zmienione od ostatniej synchronizacji niż za każdym razem przetwarzać wszystkie produkty.

Czym jest paginacja API?

Paginacja dzieli długą listę wyników na mniejsze części.

API może zwracać na przykład 100 produktów na jedno żądanie zamiast całego katalogu liczącego kilkadziesiąt tysięcy pozycji.

Kolejne strony mogą być pobierane za pomocą:

• numeru strony,
• offsetu,
• kursora,
• specjalnego tokenu następnej strony.

Integracja musi pobrać wszystkie potrzebne strony i prawidłowo zakończyć proces.

Jeżeli obsłuży tylko pierwszą stronę, zsynchronizuje jedynie część katalogu.

Filtrowanie i sortowanie danych

Dobre API pozwala ograniczyć zwracane dane za pomocą filtrów.

Można poprosić na przykład o:

• produkty zmienione od wskazanej daty,
• zamówienia o określonym statusie,
• rekordy konkretnego klienta,
• produkty z wybranej kategorii,
• dokumenty utworzone w danym okresie.

Filtrowanie zmniejsza ilość pobieranych danych i przyspiesza integrację.

Trzeba jednak sprawdzić sposób obsługi dat, stref czasowych i granicznych wartości, aby nie pominąć rekordów.

Czym są kody odpowiedzi HTTP?

Kod odpowiedzi pomaga określić wynik żądania.

Najczęściej można spotkać grupy:

• kody sukcesu,
• przekierowania,
• błędy żądania klienta,
• błędy serwera.

Przykładowe sytuacje obejmują:

• prawidłowe pobranie danych,
• utworzenie nowego rekordu,
• brak autoryzacji,
• brak uprawnień,
• nieistniejący rekord,
• nieprawidłowe dane,
• przekroczenie limitu,
• wewnętrzny błąd systemu.

Integracja nie powinna zakładać, że każda odpowiedź oznacza sukces tylko dlatego, że otrzymała jakiekolwiek dane.

Błąd techniczny a błąd biznesowy

Błąd techniczny może oznaczać:

• brak połączenia,
• niedostępność serwera,
• przekroczenie czasu,
• nieprawidłowy format odpowiedzi.

Błąd biznesowy może wystąpić mimo prawidłowego działania serwera.

Przykładowo system może odrzucić zamówienie, ponieważ:

• produkt nie istnieje,
• stan jest niewystarczający,
• klient ma blokadę,
• brakuje wymaganej wartości,
• status nie pozwala na zmianę.

Integracja powinna rozróżniać te sytuacje. Ponawianie żądania nie naprawi brakującego produktu ani nieprawidłowego numeru podatkowego.

Jak obsługiwać błędy API?

Każda integracja powinna posiadać plan obsługi błędów.

Powinna określać:

• które błędy można automatycznie ponowić,
• ile razy ponowić żądanie,
• jak długo czekać,
• kiedy zatrzymać proces,
• jak powiadomić administratora,
• jak oznaczyć nieprzetworzony rekord,
• jak wznowić synchronizację.

Błąd nie powinien znikać wyłącznie w technicznym logu, którego nikt nie kontroluje.

System powinien wyraźnie informować, że zamówienie nie trafiło do ERP albo stan produktu nie został zaktualizowany.

Czym jest ponawianie żądań?

Niektóre błędy są chwilowe. Serwer może być przeciążony albo połączenie może zostać przerwane.

Integracja może wtedy ponowić żądanie.

Nie powinna jednak robić tego natychmiast i bez limitu.

Dobre ponawianie wykorzystuje:

• rosnące odstępy pomiędzy próbami,
• maksymalną liczbę prób,
• rozpoznawanie rodzaju błędu,
• mechanizm zapobiegający duplikacji.

Ponowienie tworzenia zamówienia bez zabezpieczenia może utworzyć kilka identycznych dokumentów.

Czym jest idempotencja?

Idempotencja oznacza, że wielokrotne wykonanie tej samej operacji nie powoduje wielokrotnego utworzenia tego samego efektu.

Jest szczególnie ważna przy:

• płatnościach,
• zamówieniach,
• fakturach,
• rezerwacjach,
• przesyłkach.

Integracja może przesłać unikalny klucz operacji. Jeżeli żądanie zostanie powtórzone, system rozpozna, że dana operacja została już wykonana.

Bez takiego zabezpieczenia chwilowy błąd sieci może doprowadzić do utworzenia:

• dwóch zamówień,
• dwóch obciążeń,
• kilku etykiet kurierskich,
• powielonych klientów.

Jak zapobiegać duplikacji danych?

Integracja powinna posiadać stabilne identyfikatory łączące rekordy pomiędzy systemami.

Może zapisywać:

• ID zamówienia źródłowego,
• ID zamówienia docelowego,
• SKU produktu,
• ID klienta,
• unikalny numer operacji,
• datę ostatniej synchronizacji.

Przed utworzeniem nowego rekordu warto sprawdzić, czy powiązanie już istnieje.

Nie należy opierać rozpoznawania wyłącznie na nazwie produktu albo adresie e-mail, jeżeli systemy posiadają jednoznaczne identyfikatory.

Czym jest mapowanie danych?

Mapowanie określa, które pole jednego systemu odpowiada polu w drugim.

Przykładowo:

• SKU w WooCommerce odpowiada kodowi towaru w ERP,
• billing_first_name odpowiada imieniu klienta,
• status processing odpowiada statusowi przyjęte do realizacji,
• cena brutto odpowiada określonej wartości w systemie księgowym.

Mapowanie nie zawsze jest bezpośrednie.

Jedno pole może wymagać:

• połączenia kilku wartości,
• konwersji formatu,
• przeliczenia podatku,
• zmiany jednostki,
• przypisania według słownika,
• zastąpienia wartością domyślną.

Mapowanie statusów

Dwa systemy mogą używać innych nazw i liczby statusów.

WooCommerce może posiadać statusy:

• oczekujące na płatność,
• w trakcie realizacji,
• zrealizowane,
• anulowane,
• zwrócone.

ERP może używać własnego procesu obejmującego:

• nowe,
• zatwierdzone,
• zarezerwowane,
• wydane,
• zamknięte.

Trzeba ustalić:

• który status odpowiada któremu,
• który system może zmieniać status,
• czy synchronizacja jest jednokierunkowa,
• co zrobić z niestandardowymi statusami.

Nieprzemyślana synchronizacja dwukierunkowa może tworzyć pętlę zmian.

Który system jest źródłem prawdy?

Dla każdego rodzaju danych powinien istnieć system nadrzędny.

Przykładowo:

• ERP może być źródłem cen i stanów,
• WooCommerce źródłem treści marketingowych,
• CRM źródłem statusu szansy sprzedaży,
• operator płatności źródłem potwierdzenia transakcji.

Jeżeli dwa systemy mogą równocześnie nadpisywać tę samą wartość, trzeba ustalić priorytet.

Bez tego zmiana ceny w sklepie może zostać za chwilę zastąpiona starą ceną z ERP, a następnie ponownie wysłana do ERP.

Synchronizacja jednokierunkowa i dwukierunkowa

Synchronizacja jednokierunkowa przesyła dane z systemu A do systemu B.

Przykładowo ERP aktualizuje stany w sklepie, ale sklep nie zmienia stanów w ERP bezpośrednio.

Synchronizacja dwukierunkowa pozwala przesyłać dane w obu kierunkach.

Jest bardziej złożona, ponieważ trzeba obsłużyć:

• konflikty zmian,
• kolejność aktualizacji,
• pętle synchronizacji,
• różnice czasu,
• źródło prawdy,
• zmiany wykonane równocześnie.

Nie wdrażam dwukierunkowej synchronizacji tylko dlatego, że wydaje się bardziej kompletna. Najpierw sprawdzam, czy proces rzeczywiście jej potrzebuje.

Synchronizacja pełna i przyrostowa

Pełna synchronizacja przetwarza cały dostępny zbiór danych.

Może być potrzebna:

• przy pierwszym uruchomieniu,
• po zmianie mapowania,
• podczas odbudowy danych,
• w ramach okresowej kontroli.

Synchronizacja przyrostowa pobiera tylko rekordy zmienione od ostatniego uruchomienia.

Jest zwykle szybsza i mniej obciąża systemy.

Wymaga jednak poprawnej obsługi:

• dat modyfikacji,
• stref czasowych,
• usuniętych rekordów,
• nieudanych fragmentów procesu,
• momentu ostatniej udanej synchronizacji.

API a webhook

API i webhook współpracują ze sobą, ale działają inaczej.

W klasycznym wywołaniu API system A pyta system B:

Czy pojawiły się nowe dane?

Webhook pozwala systemowi B samodzielnie poinformować:

Właśnie wydarzyło się coś nowego.

Przykład API:

• sklep co pięć minut pyta operatora płatności o status transakcji.

Przykład webhooka:

• operator płatności wysyła informację natychmiast po zmianie statusu.

Webhook może uruchomić proces, a API zostać użyte do pobrania pełnych szczegółów zdarzenia.

API a import plikowy

Nie każda integracja musi korzystać z API.

Pliki CSV lub XML mogą być wystarczające, gdy:

• dane zmieniają się rzadko,
• proces nie wymaga natychmiastowej aktualizacji,
• system nie udostępnia API,
• katalog jest prosty,
• ważna jest łatwa kontrola danych.

API ma większe znaczenie, gdy potrzebne są:

• częste aktualizacje,
• natychmiastowa odpowiedź,
• wykonywanie operacji,
• obsługa statusów,
• automatyczne raportowanie błędów.

Dobry automatyczny plik jest lepszy niż źle zaprojektowana integracja API.

API a automatyzacja no-code

Narzędzia automatyzujące mogą korzystać z gotowych połączeń z API bez konieczności programowania całej integracji.

Pozwalają tworzyć procesy takie jak:

• po formularzu utwórz kontakt w CRM,
• po zamówieniu dodaj rekord do arkusza,
• po zmianie statusu wyślij wiadomość,
• po rezerwacji utwórz wydarzenie w kalendarzu.

Rozwiązania no-code są przydatne przy prostych i umiarkowanie złożonych procesach.

Trzeba jednak sprawdzić:

• koszt wykonanych operacji,
• limity,
• bezpieczeństwo danych,
• obsługę błędów,
• opóźnienia,
• dostępność potrzebnych pól,
• zależność od zewnętrznej platformy.

Przy krytycznym procesie sprzedażowym dedykowana integracja może zapewnić większą kontrolę i przewidywalność.

REST API w WordPressie

WordPress posiada własne REST API umożliwiające odczytywanie i modyfikowanie wybranych danych.

Może udostępniać między innymi:

• wpisy,
• strony,
• media,
• kategorie,
• użytkowników w odpowiednim zakresie,
• dane dodane przez wtyczki.

Własna wtyczka może również tworzyć dodatkowe endpointy obsługujące niestandardowe procesy.

API WordPressa może służyć do:

• budowy aplikacji korzystającej z treści WordPressa,
• integracji z zewnętrznym systemem,
• automatycznej publikacji,
• obsługi dedykowanego panelu,
• udostępniania danych własnej wtyczki.

Czy REST API WordPressa jest bezpieczne?

Samo istnienie API nie oznacza automatycznie zagrożenia.

Znaczenie ma to, jakie dane i operacje zostały udostępnione oraz jak są chronione.

Trzeba kontrolować:

• uprawnienia użytkownika,
• uwierzytelnianie,
• widoczność danych,
• walidację wejścia,
• ograniczenie liczby żądań,
• komunikaty błędów,
• aktualność WordPressa i wtyczek.

Nie należy wyłączać całego REST API bez sprawdzenia, które funkcje strony z niego korzystają. Edytor, WooCommerce i wtyczki mogą potrzebować wybranych endpointów.

WooCommerce REST API

WooCommerce udostępnia API pozwalające zarządzać danymi sklepu.

Może obejmować między innymi:

• produkty,
• warianty,
• zamówienia,
• klientów,
• kupony,
• kategorie,
• podatki,
• metody dostawy.

Może zostać wykorzystane do integracji z:

• ERP,
• systemem magazynowym,
• CRM,
• aplikacją mobilną,
• systemem raportowym,
• zewnętrznym panelem obsługi.

Klucze WooCommerce mogą posiadać uprawnienia tylko do odczytu, tylko do zapisu albo do obu rodzajów operacji.

Zakres należy ograniczyć do rzeczywistych potrzeb integracji.

API płatności

Operatorzy płatności udostępniają API pozwalające między innymi:

• utworzyć transakcję,
• przekierować użytkownika do płatności,
• sprawdzić status,
• wykonać zwrot,
• pobrać szczegóły operacji.

W płatnościach szczególnie ważne są:

• podpisy komunikatów,
• idempotencja,
• weryfikacja kwoty i waluty,
• niezależne potwierdzenie statusu,
• ochrona sekretów,
• obsługa zwrotów.

Nie należy uznawać zamówienia za opłacone wyłącznie dlatego, że użytkownik wrócił na stronę podziękowania.

Potwierdzenie powinno pochodzić z wiarygodnego komunikatu operatora albo sprawdzenia przez API.

API kurierskie

API przewoźnika może umożliwiać:

• tworzenie przesyłek,
• pobieranie etykiet,
• zamawianie odbioru,
• sprawdzanie statusu,
• wybór punktu odbioru,
• wycenę dostawy.

Integracja powinna obsługiwać różnice pomiędzy:

• przesyłką kurierską,
• punktem odbioru,
• pobraniem,
• przesyłką zagraniczną,
• paczką niestandardową.

Nie każde zamówienie można wysłać tą samą metodą. Wymiary, waga, kraj i wartość mogą wpływać na dostępne usługi.

API ERP i systemów magazynowych

Integracja sklepu z ERP może obejmować:

• produkty,
• ceny,
• stany,
• zamówienia,
• klientów,
• faktury,
• statusy realizacji.

Przed wdrożeniem trzeba ustalić:

• który system tworzy produkty,
• gdzie zmieniane są ceny,
• jak często synchronizować stany,
• jak rezerwować towar,
• co zrobić z zamówieniem anulowanym,
• jak obsłużyć produkty nieistniejące w ERP,
• jak zapisywać rabaty i koszty dostawy.

Największe problemy często nie wynikają z samego API, lecz z różnic pomiędzy procesami obu systemów.

Jak testować API?

Test powinien obejmować nie tylko idealne żądanie zakończone sukcesem.

Sprawdzam:

• prawidłowe dane,
• brak wymaganego pola,
• nieprawidłowy identyfikator,
• brak uprawnień,
• wygaśnięcie tokenu,
• przekroczenie limitu,
• niedostępność systemu,
• powtórzenie tego samego żądania,
• dużą liczbę rekordów,
• nietypowe znaki i wartości.

Testuję również pełny proces biznesowy.

Utworzenie zamówienia przez API może się udać technicznie, ale trzeba sprawdzić, czy:

• produkty są właściwe,
• kwoty się zgadzają,
• status jest prawidłowy,
• stan został zarezerwowany,
• dokument pojawił się w odpowiednim miejscu,
• ponowna próba nie tworzy duplikatu.

Środowisko testowe API

Dostawca API może udostępniać środowisko testowe nazywane sandboxem.

Pozwala ono wykonywać operacje bez wpływu na prawdziwych klientów i produkcyjne dane.

Środowisko testowe może posiadać:

• oddzielny adres,
• osobne klucze,
• przykładowe produkty,
• symulowane płatności,
• specjalne scenariusze błędów.

Trzeba pamiętać, że sandbox nie zawsze zachowuje się identycznie jak produkcja.

Po przejściu testów wykonuję kontrolowany test produkcyjny na rzeczywistym środowisku.

Logowanie integracji

Dobra integracja zapisuje informacje potrzebne do diagnostyki.

Log może zawierać:

• czas operacji,
• rodzaj żądania,
• identyfikator rekordu,
• wynik,
• kod błędu,
• liczbę prób,
• czas odpowiedzi.

Nie powinien bez potrzeby zapisywać:

• haseł,
• pełnych tokenów,
• danych kart,
• nadmiarowych danych osobowych,
• sekretów integracji.

Log musi być dostępny dla administratora, ale odpowiednio chroniony przed osobami nieuprawnionymi.

Monitoring API

Integracja może przestać działać mimo braku zmian w samym sklepie.

Przyczyną może być:

• wygaśnięcie tokenu,
• zmiana adresu API,
• nowa wersja,
• awaria dostawcy,
• zmiana certyfikatu,
• przekroczenie limitu,
• zmiana wymaganego pola.

Monitoring powinien kontrolować:

• liczbę udanych operacji,
• liczbę błędów,
• czas ostatniej synchronizacji,
• czas odpowiedzi,
• liczbę rekordów oczekujących,
• nietypowe spadki lub wzrosty.

Administrator powinien otrzymać powiadomienie, zanim brak synchronizacji zostanie zauważony przez klienta.

Czym jest wersjonowanie API?

API może zmieniać się wraz z rozwojem systemu.

Nowa wersja może:

• dodawać pola,
• zmieniać format,
• usuwać stare operacje,
• wprowadzać nowe zasady uwierzytelniania,
• zmieniać kody błędów.

Wersja może być oznaczona w adresie, nagłówku albo konfiguracji.

Integracja powinna wiedzieć, z której wersji korzysta i kiedy przestanie być ona wspierana.

Nie należy zakładać, że API będzie działać bez zmian przez wiele lat.

Czym jest wycofanie wersji API?

Dostawca może ogłosić zakończenie wsparcia starej wersji.

Proces może obejmować:

• ostrzeżenie,
• okres migracji,
• ograniczenie części funkcji,
• całkowite wyłączenie endpointów.

Firma powinna wiedzieć:

• kto utrzymuje integrację,
• gdzie zapisano jej kod,
• jak ją przetestować,
• jak szybko można wdrożyć nową wersję.

Integracja bez właściciela i dokumentacji staje się ryzykiem operacyjnym.

Wydajność integracji API

Źle zaprojektowana integracja może obciążać zarówno sklep, jak i system zewnętrzny.

Problemy mogą wynikać z:

• pobierania całego katalogu co minutę,
• wysyłania każdego produktu osobnym żądaniem,
• braku cache,
• braku kolejek,
• blokowania strony podczas synchronizacji,
• dużej liczby ponowień.

W zależności od procesu warto wykorzystać:

• synchronizację przyrostową,
• operacje zbiorcze,
• kolejkę zadań,
• przetwarzanie w tle,
• cache,
• webhooki,
• harmonogram poza godzinami największego ruchu.

Dlaczego kolejka zadań jest ważna?

Nie każda operacja musi zostać wykonana podczas oczekiwania użytkownika na załadowanie strony.

Po zamówieniu sklep może zapisać zadanie wysłania danych do ERP, a następnie wykonać je w tle.

Kolejka pozwala:

• nie blokować checkoutu,
• kontrolować liczbę równoległych żądań,
• ponawiać nieudane operacje,
• zapisywać postęp,
• obsługiwać chwilową niedostępność API.

Trzeba jednak jasno informować administratora, jeżeli zadanie nie zostało wykonane mimo kolejnych prób.

Cache danych z API

Niektórych danych nie trzeba pobierać przy każdym wyświetleniu strony.

Można czasowo zapisać:

• kursy walut,
• listę punktów,
• parametry produktu,
• dane statycznego katalogu,
• wynik zewnętrznego raportu.

Cache zmniejsza liczbę żądań i przyspiesza stronę.

Nie powinien jednak przechowywać zbyt długo danych wymagających aktualności, takich jak:

• stan magazynowy,
• status płatności,
• termin rezerwacji,
• dynamiczna cena.

Czas cache trzeba dopasować do rodzaju informacji.

Bezpieczeństwo API

Integracja API może otrzymać dostęp do ważnych danych i operacji.

Podstawowe zabezpieczenia obejmują:

• połączenie HTTPS,
• bezpieczne przechowywanie kluczy,
• ograniczone uprawnienia,
• walidację danych,
• kontrolę częstotliwości,
• logowanie operacji,
• rotację poświadczeń,
• aktualizację bibliotek,
• monitoring nietypowych działań.

Nie należy ufać danym tylko dlatego, że przyszły z zewnętrznego API.

Każdą wartość trzeba sprawdzić przed zapisaniem lub wyświetleniem.

Walidacja i sanityzacja danych

Walidacja sprawdza, czy dane mają oczekiwany format i wartość.

Może potwierdzać, czy:

• cena jest liczbą,
• e-mail ma prawidłowy format,
• status znajduje się na dozwolonej liście,
• produkt istnieje,
• ilość jest dodatnia.

Sanityzacja przygotowuje dane do bezpiecznego użycia, na przykład usuwa niedozwolone elementy tekstu.

Oba procesy są ważne zarówno dla danych wysyłanych, jak i odbieranych.

API a dane osobowe

API może przesyłać dane klientów pomiędzy sklepem, CRM, kurierem i systemem księgowym.

Trzeba określić:

• jakie dane są potrzebne,
• w jakim celu są przekazywane,
• kto je otrzymuje,
• jak długo są przechowywane,
• jak są zabezpieczone,
• czy transfer jest dokumentowany.

Nie należy przesyłać pełnego profilu klienta, jeżeli zewnętrzna usługa potrzebuje wyłącznie adresu dostawy.

Zakres danych powinien odpowiadać rzeczywistej funkcji integracji.

Czy API jest zawsze płatne?

Nie.

Dostęp może być:

• bezpłatny,
• zawarty w abonamencie,
• dostępny tylko w wyższym planie,
• rozliczany według liczby żądań,
• rozliczany według liczby rekordów,
• udostępniany po indywidualnej umowie.

Koszt integracji obejmuje nie tylko dostęp do API.

Trzeba uwzględnić:

• analizę,
• programowanie,
• testy,
• hosting,
• monitoring,
• utrzymanie,
• aktualizacje wersji,
• obsługę błędów.

Czy posiadanie API oznacza, że integracja jest możliwa?

Nie zawsze.

API może nie udostępniać wszystkich potrzebnych operacji.

Przykładowo może pozwalać pobierać zamówienia, ale nie umożliwiać:

• zmiany statusu,
• dodania numeru przesyłki,
• obsługi niestandardowych pól,
• pobrania dokumentu,
• aktualizacji wariantu.

Przed wyceną integracji trzeba sprawdzić dokumentację i potwierdzić dostępność konkretnych funkcji.

Informacja „system posiada API” jest zbyt ogólna, aby zagwarantować wykonanie dowolnego procesu.

Najczęstsze błędy podczas integracji API

Rozpoczęcie bez opisu procesu

Systemy są łączone bez ustalenia, które dane i w jakim kierunku mają być przesyłane.

Brak źródła prawdy

Dwa systemy nadpisują tę samą cenę lub status.

Mapowanie po nazwie

Produkty są łączone po tytule zamiast stabilnego SKU lub ID.

Brak obsługi paginacji

Integracja pobiera tylko pierwszą część katalogu.

Brak limitów i kolejek

Tysiące żądań są wysyłane jednocześnie.

Ponawianie bez idempotencji

Chwilowy błąd tworzy powielone zamówienia lub płatności.

Ignorowanie odpowiedzi API

System uznaje operację za zakończoną mimo zwróconego błędu.

Brak obsługi błędów biznesowych

Nieprawidłowy produkt jest ponawiany bez końca.

Klucz w publicznym kodzie

Poufne dane dostępowe można odczytać w przeglądarce.

Zbyt szerokie uprawnienia

Integracja odczytująca produkty może również usuwać zamówienia i klientów.

Jedne dane dostępowe dla wszystkich

Nie można odebrać dostępu jednemu wykonawcy bez zatrzymania całego systemu.

Brak środowiska testowego

Pierwsze operacje są wykonywane na rzeczywistych zamówieniach i płatnościach.

Brak logów

Nie wiadomo, które dane zostały przesłane i dlaczego operacja się nie udała.

Logowanie sekretów

Tokeny i dane osobowe trafiają do plików dostępnych dla nieuprawnionych osób.

Brak monitoringu

Synchronizacja nie działa od kilku dni, ale nikt nie otrzymał powiadomienia.

Brak wersjonowania

Dostawca wyłącza starą wersję API i integracja nagle przestaje działać.

Synchronizacja podczas ładowania strony

Użytkownik czeka na odpowiedź zewnętrznego systemu, a awaria API blokuje sklep.

Brak dokumentacji

Po zmianie wykonawcy nikt nie wie, jak działa mapowanie i gdzie przechowywane są klucze.

Jak samodzielnie ocenić możliwość integracji API?

Podstawową analizę można rozpocząć od odpowiedzi na kilka pytań:

1. Jaki proces ma zostać zautomatyzowany?
2. Które systemy biorą w nim udział?
3. Jakie dane mają być przesyłane?
4. W którym kierunku?
5. Który system jest źródłem prawdy?
6. Czy API udostępnia potrzebne operacje?
7. Czy dostępna jest dokumentacja?
8. Czy istnieje środowisko testowe?
9. Jak działa uwierzytelnianie?
10. Jakie są limity?
11. Czy API posiada paginację?
12. Czy udostępnia webhooki?
13. Jak wyglądają komunikaty błędów?
14. Jak rozpoznawane są produkty i klienci?
15. Czy potrzebna jest synchronizacja dwukierunkowa?
16. Jak zapobiec duplikacji?
17. Jak często dane mają być aktualizowane?
18. Kto otrzyma powiadomienie o błędzie?
19. Kto będzie utrzymywał integrację?
20. Jak obsłużyć zmianę wersji API?

Jak wygląda prawidłowy proces projektowania integracji API?

1. Opisuję proces biznesowy – ustalam, co ma się wydarzyć od początku do końca.
2. Określam systemy i odpowiedzialność – wskazuję źródło prawdy dla każdego rodzaju danych.
3. Analizuję dokumentację – sprawdzam endpointy, limity, uwierzytelnianie i błędy.
4. Przygotowuję mapowanie – łączę pola, identyfikatory, statusy i wartości.
5. Projektuję kierunek synchronizacji – unikam niepotrzebnych połączeń dwukierunkowych.
6. Ustalam sposób uruchamiania – wybieram webhook, harmonogram, kolejkę albo działanie użytkownika.
7. Projektuję obsługę błędów – rozdzielam błędy chwilowe, techniczne i biznesowe.
8. Dodaję ochronę przed duplikacją – wykorzystuję stabilne identyfikatory i idempotencję.
9. Ograniczam uprawnienia – nadaję integracji tylko potrzebny zakres.
10. Przygotowuję środowisko testowe – oddzielam testowe i produkcyjne dane dostępowe.
11. Wdrażam integrację etapami – zaczynam od kontrolowanego zakresu danych.
12. Testuję sukces i błędy – sprawdzam również ponowienia, brak połączenia i nietypowe dane.
13. Uruchamiam monitoring – kontroluję kolejki, błędy, czas odpowiedzi i ostatnią synchronizację.
14. Dokumentuję rozwiązanie – zapisuję mapowanie, dostęp, wersje i procedurę awaryjną.
15. Planuję utrzymanie – sprawdzam zmiany API, bezpieczeństwo i aktualność integracji.

Czy każda integracja wymaga programowania?

Nie.

Prosty proces może zostać zrealizowany przez:

• gotową wtyczkę,
• integrację dostarczoną przez platformę,
• narzędzie automatyzujące,
• import i eksport plikowy,
• konfigurację bez pisania własnego kodu.

Dedykowane programowanie ma większe uzasadnienie, gdy:

• proces jest nietypowy,
• gotowa integracja nie obsługuje potrzebnych pól,
• ważna jest obsługa dużej liczby danych,
• potrzebne są złożone reguły biznesowe,
• integracja jest krytyczna dla sprzedaży,
• wymagana jest pełna kontrola błędów i monitoringu.

Nie buduję własnego połączenia tylko dlatego, że jest to technicznie możliwe. Najpierw sprawdzam, czy istniejące rozwiązanie zapewnia właściwy zakres, bezpieczeństwo i możliwość utrzymania.

Najważniejsze wnioski

• API jest ustalonym sposobem komunikacji pomiędzy programami.
• Może udostępniać dane, funkcje i możliwość wykonywania operacji.
• Endpoint określa punkt API obsługujący konkretny zasób lub działanie.
• Żądanie zawiera polecenie i dane, a odpowiedź informuje o wyniku.
• Popularne metody HTTP to GET, POST, PUT, PATCH i DELETE.
• REST, SOAP i GraphQL są różnymi sposobami projektowania komunikacji.
• JSON jest popularnym formatem danych, ale API może wykorzystywać również XML i pliki.
• Dokumentacja powinna opisywać endpointy, parametry, uwierzytelnianie, limity i błędy.
• Posiadanie API nie gwarantuje, że udostępnia ono wszystkie potrzebne funkcje.
• Uwierzytelnianie rozpoznaje integrację, a autoryzacja określa jej uprawnienia.
• Kluczy i tokenów nie należy umieszczać w publicznym kodzie strony.
• Integracja powinna posiadać możliwie najmniejszy zakres uprawnień.
• Limity API wymagają kontrolowanych ponowień i kolejek.
• Paginacja musi zostać obsłużona, aby pobrać cały zbiór danych.
• Błędy techniczne i biznesowe wymagają innej reakcji.
• Idempotencja pomaga zapobiegać wielokrotnemu tworzeniu zamówień, płatności i dokumentów.
• Stabilne identyfikatory są podstawą prawidłowego łączenia danych.
• Mapowanie określa odpowiedniki pól, statusów i wartości pomiędzy systemami.
• Dla każdego rodzaju danych trzeba ustalić system będący źródłem prawdy.
• Synchronizacja dwukierunkowa jest bardziej złożona i nie zawsze potrzebna.
• Webhook informuje o zdarzeniu, a API może służyć do pobrania lub zmiany danych.
• WordPress i WooCommerce posiadają API umożliwiające tworzenie integracji.
• Operacje płatnicze powinny być potwierdzane przez wiarygodny komunikat systemu, a nie samo wejście na stronę podziękowania.
• Integracja powinna działać w tle, jeżeli zewnętrzne API nie musi blokować działania użytkownika.
• Logi, monitoring i powiadomienia są częścią integracji, a nie opcjonalnym dodatkiem.
• API może zmienić wersję, dlatego integracja wymaga właściciela, dokumentacji i utrzymania.
• Dobrze zaprojektowane połączenie zaczyna się od procesu biznesowego, a nie od pierwszego żądania technicznego.

Nie wiesz, czy dwa systemy można bezpiecznie połączyć przez API?

Podczas analizy sprawdzam nie tylko to, czy oba systemy posiadają API. Rozpisuję przepływ danych, źródła prawdy, identyfikatory, statusy, limity, błędy i sposób zabezpieczenia całego procesu.

Mogę wskazać ryzyko powstawania duplikatów, konfliktów synchronizacji, utraty zamówień oraz sytuacje, w których gotowa integracja nie obsługuje rzeczywistych potrzeb firmy.

Nie zakładam automatycznie, że potrzebne jest kosztowne rozwiązanie dedykowane. Najpierw sprawdzam możliwości oficjalnych integracji, wtyczek, automatyzacji i importów. Dopiero wtedy wybieram rozwiązanie zapewniające odpowiednią kontrolę, niezawodność i możliwość dalszego rozwoju.