Integracje API – łączymy stronę z systemami firmy

Większość firm zaczyna od połączeń, które bezpośrednio wpływają na obsługę zamówień. Sklep internetowy łączymy z firmami kurierskimi, żeby etykiety i numery śledzenia generowały się z poziomu panelu. Oferty i stany magazynowe synchronizujemy z marketplace’ami, by ten sam egzemplarz produktu nie sprzedał się dwa razy. Bramki płatności przekazują statusy transakcji, a dane do faktur trafiają do programu księgowego lub systemu fakturowania. Przy większej skali w grę wchodzi wymiana danych z systemem ERP – opisujemy ją szczegółowo na podstronach poświęconych poszczególnym systemom.

Zewnętrzne API bywają niedostępne: serwer kuriera przechodzi przerwę techniczną, marketplace zwraca błąd przekroczenia limitu zapytań, a bramka płatności odpowiada z opóźnieniem. Integracja, która wysyła dane raz i zakłada sukces, prędzej czy później coś zgubi. Dlatego operacje wykonujemy asynchronicznie, przez kolejkę zadań. Każde zadanie ma zapisany stan, liczbę prób i treść ostatniego błędu. Po nieudanej próbie system odczekuje i ponawia, a po wyczerpaniu prób oznacza zadanie do ręcznego sprawdzenia.

Webhooki przyjmujemy z weryfikacją podpisu lub tokenu, żeby nikt nie mógł podszyć się pod dostawcę. Dbamy też o idempotentność – ten sam komunikat odebrany dwa razy nie utworzy dwóch faktur ani dwóch przesyłek. Przestrzegamy też limitów zapytań dostawcy, rozkładając duże synchronizacje w czasie. To szczegóły, których nie widać w dniu uruchomienia, ale to one decydują o tym, czy integracja działa spokojnie przez kolejne miesiące.

Dla wielu popularnych połączeń istnieją gotowe wtyczki i moduły – i często warto od nich zacząć. Sprawdzamy, czy dostępne rozszerzenie obsługuje Twój przypadek, jest regularnie aktualizowane i nie obciąża nadmiernie strony. Kod dedykowany piszemy wtedy, gdy wtyczka nie przenosi potrzebnych pól, wymusza sposób pracy niezgodny z Twoim procesem albo gdy łączysz systemy, dla których gotowego modułu po prostu nie ma. Przy prostych przepływach między aplikacjami w chmurze rozważamy też platformy Make lub Zapier.

Każdy system opisuje te same rzeczy inaczej. Sklep ma statusy zamówień, kurier swoje statusy przesyłek, a program księgowy własne typy dokumentów. Przed napisaniem kodu przygotowujemy tabelę mapowania: które pole odpowiada któremu, jak zamieniamy wartości, co robimy z danymi, których drugi system nie obsługuje.

Mapowanie uzgadniamy z osobami, które pracują z danymi na co dzień. Dzięki temu integracja odzwierciedla rzeczywiste procesy w firmie, a nie tylko techniczne możliwości interfejsów.

Integrację budujemy i testujemy na środowiskach testowych obu stron, jeśli dostawca je udostępnia. Sprawdzamy typowe przypadki, ale też sytuacje brzegowe: zamówienie z kilkoma przesyłkami, produkt bez wymaganego pola, przerwę w połączeniu w połowie wysyłki danych.

Uruchomienie planujemy etapami. Najpierw integracja działa w trybie obserwacji, w którym zapisuje, co by zrobiła, potem obsługuje część danych, a na końcu przejmuje całość. W razie problemu możemy szybko wrócić do poprzedniego sposobu pracy.