Wielu klientów przychodzi do mnie z problemem: integracja działała przez kilka miesięcy, a potem nagle przestała. W większości przypadków winowajcą jest brak mechanizmów odporności na błędy. API partnera może być chwilowo niedostępne, payload może być niepoprawny, a autoryzacja może wygasnąć bez powiadomienia. Projektując integracje od początku z myślą o awariach, oszczędzasz sobie i swojemu zespołowi wielu bezsennych nocy.
Dlaczego integracje wymagają szczególnej uwagi?
W dzisiejszym świecie aplikacje rzadko działają w izolacji. Łączymy sklepy z marketplace'ami, CRM z systemami księgowymi, narzędzia sprzedażowe z magazynami. Każde z tych połączeń to potencjalny punkt awarii. Jeśli projektujesz integrację zakładając, że wszystko zawsze będzie działać idealnie, prędzej czy później spotka Cię przykra niespodzianka.
Kluczowym elementem jest zrozumienie, że nie kontrolujesz wszystkich systemów w łańcuchu. API partnera może zmienić się bez ostrzeżenia, certyfikat SSL może wygasnąć, a klucz API może zostać odwołany. Twoim zadaniem jest zaprojektowanie systemu, który poradzi sobie z każdą z tych sytuacji bez utraty danych i bez ręcznej interwencji.
Kolejki i mechanizmy retry
Zamiast wywoływać API zewnętrzne synchronicznie, co blokuje użytkownika do czasu otrzymania odpowiedzi, użyj kolejek zadań. Dzięki temu żądanie jest zapisywane do kolejki i przetwarzane w tle. Jeśli API nie odpowiada, mechanizm retry spróbuje ponownie za 10 sekund, potem za 30, potem za 2 minuty. Po wyczerpaniu prób błąd jest zapisywany, a zespół otrzymuje alert.
Wykładniczy backoff to standardowa praktyka, ale warto też dodać element losowości (jitter), aby uniknąć efektu „thundering herd", gdy wiele żądań czeka na to samo API i wszystkie próbują połączyć się jednocześnie po jego przywróceniu.
Weryfikacja webhooków i bezpieczeństwo
Odbierając webhooki, zawsze weryfikuj ich źródło. Jeśli API wspiera podpisywanie wiadomości (HMAC, secret key), korzystaj z tego mechanizmu. W przypadku braku podpisu przynajmniej waliduj adres IP nadawcy i stosuj stały klucz sekretny w nagłówku. Nigdy nie przetwarzaj webhooka bez weryfikacji, bo możesz paść ofiarą ataku polegającego na podszyciu się pod zaufane źródło.
Idempotentność endpointów
Zaprojektuj endpointy odbierające webhooki tak, aby były idempotentne. Oznacza to, że wielokrotne wysłanie tego samego zdarzenia nie powoduje skutków ubocznych. W praktyce realizuje się to przez zapisanie identyfikatora zdarzenia z API nadawcy i sprawdzanie przed przetworzeniem, czy już go obsłużyliśmy. Dzięki temu nawet jeśli webhook zostanie dostarczony dwukrotnie (co zdarza się częściej niż myślisz), nie stworzysz duplikatu zamówienia ani nie wyślesz dwa razy tej samej faktury.
Monitoring i alerty w czasie rzeczywistym
Każda integracja powinna logować trzy rzeczy: co się wydarzyło, kiedy i z jakim skutkiem. Bez dziennika zdarzeń nie masz szans dowiedzieć się, co poszło nie tak i dlaczego. Samo logowanie to jednak za mało — potrzebujesz alertów w czasie rzeczywistym dla sytuacji krytycznych: nagły wzrost błędów, spadek wydajności, przerwane połączenie z API partnera.
W moich projektach używam powiadomień Slack dla alertów średniego priorytetu i SMS lub telefon dla awarii krytycznych, które wymagają natychmiastowej reakcji. Dobrze skonfigurowany monitoring to ubezpieczenie na wypadek, gdy coś pójdzie nie tak w środku nocy.
Podsumowanie
Projektowanie integracji to nie tylko podłączenie dwóch systemów. To zaprojektowanie procesu, który poradzi sobie z awarią każdego z elementów składowych. Kolejki, retry, weryfikacja, idempotentność i monitoring to fundamenty, na których warto oprzeć każdą integrację, niezależnie od jej skali.
Najczęściej zadawane pytania
Czy każde API wymaga użycia kolejki?
Nie, proste integracje z szybkimi i niezawodnymi API mogą działać synchronicznie. Kolejki warto stosować tam, gdzie API jest zawodne, wolne lub gdzie utrata żądania byłaby krytyczna.
Jak długo przechowywać logi integracji?
Minimum 30 dni dla standardowych integracji i 90 dni dla systemów księgowych i płatności, gdzie wymagają tego przepisy. Po tym czasie logi można archiwizować lub usuwać.
Czy webhook jest bezpieczniejszy niż polling?
Webhooki są szybsze i mniej obciążają API, ale wymagają starannej weryfikacji bezpieczeństwa. Polling z kolei jest prostszy i łatwiejszy do zabezpieczenia, ale generuje większy ruch sieciowy i opóźnienia.
Planowanie awaryjne i scenariusze failover
Nawet najlepiej zaprojektowana integracja może ulec awarii. Dlatego warto przygotować scenariusze awaryjne: co się dzieje, gdy API partnera nie odpowiada przez dłuższy czas?
Czy zamówienia są zapisywane w kolejce i realizowane później, czy klient otrzymuje komunikat o błędzie?
W praktyce stosuję wzorzec Circuit Breaker. Gdy API zaczyna zwracać błędy, obwód otwiera się i wszystkie żądania są natychmiast odrzucane bez próby połączenia. Po określonym czasie obwód przechodzi w stan półotwarty i pozwala na pojedyncze żądanie testowe. Jeśli się powiedzie, obwód zamyka się i normalne działanie zostaje przywrócone.
Testowanie odporności integracji
Przed wdrożeniem integracji na produkcję przetestuj jej zachowanie w scenariuszach awaryjnych: opóźnienia sieciowe powyżej 5 sekund, odpowiedzi z kodem 500, puste odpowiedzi, niepoprawne JSON, wygaśnięcie certyfikatu SSL. Narzędzia takie jak Toxiproxy czy WireMock pozwalają symulować te scenariusze w środowisku testowym.
Jak dokumentować integracje dla zespołu?
Dokumentacja techniczna integracji powinna zawierać opis przepływu danych, wykaz endpointów API wraz z metodami autoryzacji, konfigurację kolejek i retry, instrukcję uruchomienia lokalnego, scenariusze błędów i procedury awaryjne oraz kontakt do wsparcia technicznego każdego z systemów.
👉 Potrzebujesz integracji? Zobacz nasze Integracje e-commerce i dowiedz się, jak łączymy systemy sprzedażowe.
👉 Zarządzasz sprzedażą w wielu kanałach? Zobacz ShipNOrder.
📖 Zobacz case study: Integracja sprzedaży omnichannel — jak skróciliśmy czas obsługi zamówienia o 40%.