REST API, webhook czy plik — jak wybrać sposób integracji

REST API, webhook i plik nie są trzema wersjami tego samego rozwiązania. Każdy mechanizm odpowiada na inny sposób inicjowania pracy. API pozwala klientowi poprosić o dane lub zmianę, webhook przekazuje informację o zdarzeniu z inicjatywy systemu źródłowego, a plik dostarcza paczkę rekordów w ustalonym cyklu. Wybór powinien wynikać z czasu reakcji, wolumenu, możliwości systemów oraz kosztu odtworzenia procesu po błędzie.

Najczęstszy błąd to decyzja oparta wyłącznie na nowoczesności technologii. Firma wybiera API, choć dostawca ogranicza liczbę wywołań i nie pozwala pobrać zmian od ostatniej synchronizacji. Albo odrzuca plik, mimo że system księgowy zamyka dane raz dziennie, a proces nie wymaga reakcji w sekundach. Dobra architektura jest wystarczająco szybka, możliwa do utrzymania i zrozumiała dla osób odpowiadających za proces.

Szybka tabela wyboru

Kryterium	REST API	Webhook	Plik, np. SFTP
kto inicjuje	system potrzebujący danych	system, w którym zaszło zdarzenie	harmonogram lub operator
typowy czas reakcji	na żądanie	bliski rzeczywistemu	minuty, godziny lub doba
najlepszy zakres	odczyt i zmiana konkretnych obiektów	sygnał o zmianie	paczki i uzgodnienia wsadowe
główne ryzyko	limity, wersje, częściowe błędy	duplikaty, kolejność, niedostępny odbiornik	niepełny plik, ponowne przetworzenie
odtwarzanie	ponowne wywołanie lub odczyt stanu	kolejka, retry i pobranie stanu	archiwum, manifest i ponowny import
dobry przykład	utworzenie zamówienia w ERP	informacja o opłaceniu zamówienia	nocny eksport kartotek lub uzgodnienie stanów

Ta tabela nie zwalnia z oceny ograniczeń konkretnego produktu. „Ma API” może oznaczać pełny interfejs z dokumentacją, ale także kilka operacji bez filtrowania zmian, testowego środowiska i stabilnych identyfikatorów. Zanim powstanie estymacja, trzeba sprawdzić dokumentację, limity, sposób uwierzytelnienia, wersjonowanie oraz zachowanie przy błędzie.

Kiedy wybrać REST API

REST API jest dobrym wyborem, gdy integracja musi wykonać konkretną operację w wybranym momencie: pobrać kartę produktu, sprawdzić dostępność, utworzyć dokument albo zaktualizować status. System wywołujący kontroluje czas i może zdecydować, co zrobić z odpowiedzią.

W praktyce liczą się nie tylko adresy endpointów. OpenAPI Specification opisuje standardowy sposób przedstawiania operacji, parametrów i modeli danych HTTP API. Maszynowy kontrakt ułatwia generowanie klienta, walidację oraz wykrycie, że dostawca zmienił wymagane pole. Nie mówi jednak, czy ponowne utworzenie dokumentu jest bezpieczne ani który status biznesowy ma pierwszeństwo.

Trzeba rozróżnić odczyt od zapisu. Wielokrotne pobranie produktu zwykle nie zmienia stanu systemu. Wielokrotne wysłanie polecenia utworzenia faktury może już utworzyć duplikaty. RFC 9110 definiuje pojęcie idempotentności metod HTTP, lecz odpowiedzialność za bezpieczny proces nie kończy się na wyborze metody. Integracja powinna przekazywać własny, stabilny klucz operacji, a system docelowy rozpoznawać, że ten sam biznesowy dokument był już obsłużony.

API wybierz szczególnie wtedy, gdy:

• potrzebujesz odpowiedzi natychmiast przed kolejnym krokiem procesu;
• pracujesz na pojedynczych obiektach lub niewielkich stronach wyników;
• dostawca udostępnia filtrowanie zmian, stabilne identyfikatory i czytelne błędy;
• integracja może bezpiecznie przestrzegać limitów wywołań;
• masz środowisko testowe albo możliwość użycia danych kontrolnych.

Nie zakładaj, że odpytywanie API co kilka sekund daje prawdziwy czas rzeczywisty. Przy dużej liczbie obiektów może jedynie generować koszt, a mimo to pozostawiać opóźnienie. Wtedy przydaje się webhook lub mechanizm zdarzeniowy.

Kiedy webhook jest właściwym sygnałem

Webhook odwraca kierunek inicjowania. System źródłowy wysyła żądanie do wskazanego odbiornika, gdy wydarzy się coś istotnego: płatność została potwierdzona, zamówienie zmieniło status albo przesyłka otrzymała numer. Odbiorca nie musi stale pytać „czy coś się zmieniło?”.

Webhook nie gwarantuje jednak, że zdarzenie przyjdzie dokładnie raz i we właściwej kolejności. Dokumentacja Stripe dotycząca webhooków jest dobrym przykładem wymagań produkcyjnych: opisuje automatyczne ponowienia, możliwość duplikatów, brak gwarancji kolejności i potrzebę szybkiego zwrócenia odpowiedzi 2xx. To zachowanie konkretnego dostawcy, ale pokazuje pytania, które trzeba zadać każdemu systemowi wysyłającemu zdarzenia.

Bezpieczny odbiornik webhooka powinien:

1. zweryfikować podpis albo inny mechanizm autentyczności;
2. sprawdzić typ i minimalny schemat zdarzenia;
3. zapisać zdarzenie do trwałej kolejki;
4. szybko potwierdzić odbiór;
5. przetwarzać logikę biznesową poza żądaniem HTTP;
6. pamiętać identyfikator i ignorować duplikaty;
7. mieć proces pobrania aktualnego stanu, jeśli brakuje wcześniejszego zdarzenia.

Często webhook powinien być sygnałem, a nie pełnym źródłem prawdy. Odbiorca dostaje identyfikator zamówienia, po czym przez API pobiera jego bieżący stan. Dzięki temu spóźnione zdarzenie nie musi cofać procesu. Nadal warto uruchamiać okresowe uzgodnienie, które znajdzie obiekty pominięte wskutek długiej awarii lub błędnej konfiguracji subskrypcji.

Kiedy plik jest rozsądnym kontraktem

Wymiana CSV, XML lub JSON przez SFTP nie jest automatycznie rozwiązaniem gorszym. Dobrze pasuje do procesów wsadowych, starszych systemów oraz dużych paczek danych, których nie trzeba obsłużyć natychmiast. Plik jest też czytelnym artefaktem audytowym: można go zarchiwizować, porównać i ponownie przetworzyć.

Problem zaczyna się wtedy, gdy plik nie ma kontraktu. Nazwa export_final_2.csv, brak wersji formatu i ręczne przenoszenie między folderami szybko prowadzą do niepewności. Produkcyjna wymiana plikowa powinna określać:

• kodowanie, separator, format dat i strefę czasową;
• wymagane kolumny oraz sposób oznaczania braku wartości;
• wersję schematu i datę obowiązywania;
• nazwę pliku z jednoznacznym identyfikatorem paczki;
• sumę kontrolną albo manifest kompletności;
• publikację atomową, aby odbiorca nie pobrał pliku w trakcie zapisu;
• katalogi incoming, processed i error lub ich odpowiednik;
• regułę ponownego importu tej samej paczki;
• raport wyniku z liczbą rekordów przyjętych i odrzuconych.

Plik wybierz, gdy system źródłowy nie ma stabilnego API, dane są domykane w cyklu, operujesz na dużym zbiorze albo potrzebujesz prostego mechanizmu przekazania do środowiska o ograniczonej łączności. Nie używaj go jako pretekstu do braku walidacji i monitoringu.

Najczęściej wygrywa model hybrydowy

Rzeczywisty proces może używać wszystkich trzech mechanizmów, ale każdy musi mieć jasno określoną rolę. Przykład sprzedażowy wygląda tak:

• webhook informuje, że płatność została potwierdzona;
• kolejka zapisuje zdarzenie i odseparowuje chwilową awarię ERP;
• REST API pobiera pełne zamówienie i tworzy dokument w ERP;
• API WMS przyjmuje dyspozycję po kontroli warunków;
• nocny plik zawiera zestawienie zamówień i służy do uzgodnienia braków;
• raport pokazuje dokumenty, które wymagają decyzji operatora.

W takiej architekturze nie chodzi o mnożenie technologii. Kanały wzajemnie ograniczają swoje słabości: webhook daje szybkość, API bieżący stan, a plik kontrolny możliwość zbiorczego porównania. Jeżeli proces nie potrzebuje takiej odporności, prostszy wariant będzie lepszy.

Pięć pytań przed decyzją

Przed wyborem transportu odpowiedz na pięć pytań. Jak szybko biznes rzeczywiście potrzebuje danych? Który system może zainicjować wymianę? Czy operacja jest bezpieczna przy powtórzeniu? Jak wykryjesz brak albo rozbieżność? Kto otrzyma informację, kiedy automat nie podejmie decyzji?

Ostatnie pytanie jest często pomijane. OpenTelemetry opisuje obserwowalność przez logi, metryki i ślady pozwalające zrozumieć zachowanie systemu. Dla integracji biznesowej do tych sygnałów trzeba dodać kontekst: numer zamówienia, źródło, cel, etap, liczbę prób i wynik walidacji. Wtedy alarm „pięć błędów” zmienia się w listę pięciu dokumentów, które można naprawić.

Jeśli wybierasz mechanizm dla ERP, WMS, e-commerce lub aplikacji wewnętrznej, zacznij od procesu i warunków odtworzenia, a nie od skrótu technologicznego. W KARQIS pomagamy projektować i wdrażać takie integracje etapami. Możesz też opisać systemy i jeden problematyczny przepływ, aby ustalić, który wariant będzie wystarczający bez budowania zbędnej infrastruktury.