Dwukierunkowa integracja API z systemem Nuvolo - statusy, komentarze i karty pracy w czasie rzeczywistym

Problem: dwa systemy serwisowe i jedno zlecenie w dwóch miejscach

Gdy zlecenie żyje równolegle w dwóch systemach, każdą zmianę trzeba przenieść na drugą stronę. Bez integracji robi to człowiek - z opóźnieniem i ryzykiem pomyłki.

Rozwiązanie: pełna integracja API i webhooków z warstwą mapowania

Locatick łączy się z Nuvolo w obu kierunkach. Zdarzenia ze zleceń - zmiany statusów, komentarze, załączniki i karty pracy - są wysyłane do Nuvolo w czasie rzeczywistym przez webhook. Wysyłka przechodzi przez kolejkę, która przy błędzie ponawia próbę do 3 razy, a gdy wszystkie zawiodą, wysyła powiadomienie o nieudanej synchronizacji.

Statusy i priorytety tłumaczy osobna warstwa mapowania. Nuvolo może pobrać jej aktualną wersję z dedykowanego endpointu, więc obie strony korzystają z tego samego słownika. W drugą stronę - z Nuvolo do Locatick - działa osobny mechanizm synchronizacji zwrotnej z lokalnym cache mapowania, bo Nuvolo nie udostępnia API do pobierania ostatnio zmienionych zadań.

Całość zabezpiecza przełącznik środowiskowy: po wdrożeniu kodu integracja jest domyślnie wyłączona i włącza się ją dopiero po testach end-to-end.

Jak działa integracja Locatick z Nuvolo - krok po kroku

Co daje integracja: jedno zlecenie, ten sam stan w dwóch systemach

Integracja systemu serwisowego przez API - jak połączyć FSM z innymi systemami

Integracje API to najgłębszy sposób łączenia systemu serwisowego z resztą narzędzi w firmie. Poniżej najważniejsze decyzje, które trzeba podjąć przy takim projekcie.

Czym różni się integracja jednokierunkowa od dwukierunkowej?

Integracja jednokierunkowa przesyła dane tylko z jednego systemu do drugiego, na przykład zlecenia z CRM do systemu serwisowego. Integracja dwukierunkowa dodatkowo odsyła zmiany z powrotem, dzięki czemu oba systemy pokazują ten sam stan zlecenia. Pierwsza wystarcza, gdy drugi system jest wyłącznie źródłem danych. Druga jest potrzebna wtedy, gdy obie strony aktywnie pracują na tych samych zleceniach - jedni zmieniają statusy w aplikacji mobilnej, inni komentują lub zamykają sprawy w swoim systemie. Dwukierunkowość oznacza więcej pracy projektowej: trzeba ustalić, który system jest nadrzędny dla którego pola, jak tłumaczyć statusy i co zrobić, gdy zmiana przyjdzie z obu stron prawie jednocześnie. W przypadku Nuvolo kierunek Locatick → Nuvolo działa w czasie rzeczywistym przez webhook, a kierunek Nuvolo → Locatick obsługuje osobny mechanizm synchronizacji zwrotnej. Przy planowaniu warto też zdecydować, które dane w ogóle muszą wracać - nie każde pole wymaga synchronizacji w obie strony, a każde dodatkowe pole to kolejne reguły do utrzymania.

Kiedy firma serwisowa potrzebuje integracji API, a kiedy wystarczy import lub mail?

Integracja API jest potrzebna, gdy liczy się bieżący stan danych i wymiana działa w obu kierunkach. Jeśli zlecenia przychodzą mailem w powtarzalnym formacie, często wystarczy parser, który zamienia wiadomości w zadania - tak jak w automatycznym parserze zgłoszeń mailowych. Jeśli dane zmieniają się raz dziennie lub rzadziej, dobrym wyborem bywa cykliczny import plików CSV. API wchodzi do gry, gdy dwa systemy mają jednocześnie prowadzić to samo zlecenie: statusy, komentarze, załączniki i karty pracy mają być widoczne po obu stronach od razu, a nie po nocnym imporcie. W praktyce wiele firm łączy te podejścia - parser przyjmuje zgłoszenia, import aktualizuje dane referencyjne, a API spina procesy, w których liczy się czas. Wybór podejścia warto oprzeć na trzech pytaniach: jak szybko dane muszą być aktualne, w ilu kierunkach mają płynąć i czy drugi system udostępnia API. Odpowiedzi zwykle same wskazują najprostsze rozwiązanie, które spełni wymagania.

Jak działa webhook w systemie serwisowym?

Webhook to automatyczne powiadomienie wysyłane przez system w momencie, gdy coś się wydarzy - na przykład technik zmieni status zlecenia, doda zdjęcie albo podpisze kartę pracy. Zamiast co kilka minut pytać system, czy pojawiły się zmiany, drugi system dostaje informację od razu. W Locatick webhooki są punktem startowym wielu automatyzacji: synchronizacji z kalendarzem, tworzenia zleceń kontynuacji czy integracji z zewnętrznymi systemami. Sam webhook nie gwarantuje jednak dostarczenia danych - jeśli system docelowy w danej chwili nie odpowiada, wiadomość może przepaść. Dlatego w integracji z Nuvolo zdarzenia z webhooka trafiają do kolejki, która ponawia wysyłkę do 3 razy i zgłasza nieudane próby. Dopiero takie połączenie daje szybkość webhooka i niezawodność, jakiej wymaga proces serwisowy. Przy projektowaniu warto też ustalić, które zdarzenia mają uruchamiać webhook - wysyłanie wszystkiego obciąża oba systemy, a zbyt wąski wybór sprawia, że część zmian nie dociera na drugą stronę.

Dlaczego mapowanie statusów i priorytetów to kluczowa część integracji?

Dwa systemy serwisowe niemal nigdy nie mają identycznych słowników. Jeden ma trzy statusy, drugi siedem. Jeden mówi o pilności w skali od 1 do 4, drugi używa nazw opisowych. Bez warstwy mapowania integracja przesyła wartości, których druga strona nie rozumie, albo przypisuje je do złego etapu. Mapowanie to tabela reguł, która mówi, jak status lub priorytet z jednego systemu przekłada się na drugi. W integracji z Nuvolo mapowanie jest osobną warstwą, a Nuvolo może pobrać aktualną wersję przez dedykowany endpoint. Dzięki temu obie strony korzystają z tego samego słownika i nie trzeba ręcznie pilnować, czy konfiguracja po obu stronach jest zgodna. To właśnie na mapowaniu najczęściej rozbijają się integracje robione na szybko. Mapowanie warto przygotować razem z osobami, które na co dzień pracują w obu systemach. To one wiedzą, który status oznacza na przykład, że technik jest już w drodze, a który, że czeka na części - i jak te sytuacje rozumie druga strona.

Co zrobić, gdy drugi system nie ma API do pobierania ostatnich zmian?

Wiele systemów udostępnia API do zapisu, ale nie pozwala zapytać o zadania zmienione od ostatniej synchronizacji. Tak jest w przypadku Nuvolo. Rozwiązaniem jest osobny mechanizm synchronizacji zwrotnej po stronie Locatick, który sam pilnuje, co już zostało przeniesione, i korzysta z lokalnego cache mapowania. Cache pozwala szybko przetłumaczyć statusy i priorytety bez odpytywania drugiego systemu przy każdej operacji. Takie podejście wymaga więcej pracy niż prosta integracja, ale nie zmusza klienta do zmiany systemu ani nie uzależnia projektu od rozbudowy API po drugiej stronie. To typowa sytuacja przy integracjach z systemami, które nie były projektowane z myślą o wymianie danych w obie strony. Przy takim mechanizmie ważne jest też jasne określenie, który system ma pierwszeństwo, gdy ta sama informacja zmieni się w obu miejscach. Bez tej reguły synchronizacja zwrotna mogłaby nadpisywać świeższe dane starszymi. Dlatego logikę synchronizacji zwrotnej projektuje się razem z mapowaniem, a nie jako osobny dodatek.

Jak zabezpieczyć integrację przed utratą danych?

Podstawą jest założenie, że połączenie czasem zawiedzie - z powodu przerwy w działaniu, wygasłego tokena dostępowego albo przeciążenia serwera. Dobra integracja nie wysyła danych jednorazowo, tylko przez kolejkę, która ponawia próbę po błędzie. W integracji z Nuvolo kolejka podejmuje do 3 prób, a jeśli wszystkie się nie powiodą, wysyła powiadomienie o nieudanej synchronizacji. Drugim elementem jest monitoring: zespół musi wiedzieć, że coś się nie zsynchronizowało, zanim zauważy to klient. Trzeci to jasny podział odpowiedzialności za dostępy - tokeny API i uprawnienia po obu stronach muszą być uzgodnione między zespołami, bo to najczęstsze źródło problemów po uruchomieniu integracji na produkcji. Warto również przewidzieć, co dzieje się ze zdarzeniem po wyczerpaniu prób - czy czeka na ręczne ponowienie, czy trafia na osobną listę błędów. Jasna procedura sprawia, że powiadomienie o nieudanej synchronizacji kończy się konkretnym działaniem, a nie tylko kolejnym mailem w skrzynce.

Jak bezpiecznie uruchomić integrację na produkcji?

Najbezpieczniej oddzielić wdrożenie kodu od włączenia integracji. W projekcie z Nuvolo integracja jest domyślnie wyłączona przełącznikiem środowiskowym - kod może trafić na produkcję razem z innymi zmianami, ale nie zacznie wysyłać danych, dopóki zespół świadomie jej nie włączy. Przed włączeniem wykonuje się testy end-to-end: tworzy się zlecenia testowe, zmienia statusy, dodaje komentarze i załączniki, a następnie sprawdza, czy wszystko pojawiło się po drugiej stronie we właściwej formie. Dopiero po pozytywnym wyniku testów integracja startuje na prawdziwych danych. Takie podejście chroni przed sytuacją, w której niedokończona integracja zaczyna przypadkowo zmieniać zlecenia w systemie klienta. Przełącznik przydaje się także później - gdy po stronie drugiego systemu trwają prace serwisowe albo zmiana konfiguracji, integrację można czasowo wyłączyć bez cofania wdrożenia. Po zakończeniu prac wystarczy włączyć ją ponownie i sprawdzić, czy dane po obu stronach są zgodne.

Najczęstsze pytania o dwukierunkową integrację API