Klient wypełnia formularz, a pracownik przepisuje dane do arkusza i panelu. Integracja może połączyć te kroki, ale wymaga czegoś więcej niż działającego połączenia. Trzeba ustalić, gdzie znajduje się aktualny zapis sprawy i jak system wróci do pracy po błędzie.
Narysuj przepływ danych przed napisaniem integracji
Zapisz, skąd pochodzi informacja, do którego systemu trafia i kto może ją zmienić. Przykładowo formularz tworzy zgłoszenie, CRM przechowuje status obsługi, a arkusz pokazuje raport. Jeżeli każda kopia może niezależnie zmieniać status, szybko powstaną sprzeczności.
Ustal wspólny identyfikator sprawy oraz mapowanie pól. Zwróć uwagę na puste wartości, format dat, nazwy statusów i sposób aktualizacji kontaktu. Zgodność nazw pól nie oznacza jeszcze, że obie aplikacje rozumieją je tak samo.
API służy do zapytań, webhook informuje o zdarzeniu
Przez API aplikacja może pobrać stan zamówienia albo utworzyć rekord. Webhook to żądanie wysłane przez drugi system, np. po zmianie statusu płatności. Często potrzebne są oba mechanizmy: zdarzenie uruchamia pracę, a zapytanie API dostarcza aktualne dane.
Odbiorca webhooka powinien weryfikować jego autentyczność według dokumentacji dostawcy. W przypadku podpisów znaczenie ma również postać danych wykorzystana do weryfikacji. Sekrety i klucze przechowuj po stronie serwera oraz ogranicz ich uprawnienia do potrzeb integracji.
Przygotuj się na powtórzenia i brak odpowiedzi
Nie zakładaj, że zdarzenia przyjdą dokładnie raz i we właściwej kolejności. Przykładowo dokumentacja Stripe opisuje powtarzające się webhooki oraz brak gwarancji kolejności. Integracja powinna rozpoznawać obsłużone zdarzenia i unikać powtórnego wykonania tej samej operacji biznesowej.
Gdy żądanie kończy się timeoutem, wynik może być nieznany: drugi system mógł już zapisać rekord. Ponowienie bez kontroli grozi duplikatem. Jeśli API wspiera klucze idempotencji, użyj ich zgodnie z jego zasadami. W pozostałych przypadkach zaplanuj sprawdzenie wyniku i własne powiązanie operacji.
Zapewnij obsłudze widoczność błędów
- zapisuj identyfikator operacji, etap i wynik,
- testuj niepełne dane, duplikaty i niedostępność API,
- ustal limit ponowień i sposób ręcznego wznowienia,
- oddziel środowisko testowe od produkcyjnego,
- wyznacz osobę odpowiedzialną za reakcję na alerty.
Integracja wymaga utrzymania, gdy zmieniają się uprawnienia, format danych lub wersja API. Dodaj okresowe porównanie danych między systemami. To pozwala znaleźć sprawy, które zostały pominięte mimo pozornie poprawnej pracy połączenia.
Potrzebujesz pomocy?