Freshdesk — konfiguracja, integracje

Freshdesk API pozwala działowi IT połączyć zgłoszenia pracowników z firmowymi narzędziami. Korzystanie z interfejsu wymaga konta Freshdesk z włączonym dostępem do API.¹
Ten poradnik dotyczy przyjmowania zgłoszeń, automatyzacji, integracji i diagnozowania problemów. W wersji 2 Freshdesk API obsługuje zgłoszenia przez endpoint /api/v2/tickets².

Czym jest Freshdesk API w obsłudze zgłoszeń pracowników?

Projekt integracji wymaga ustalenia, które zgłoszenia należą do zespołu IT oraz czy system zewnętrzny będzie je tworzył, odczytywał czy aktualizował. Te decyzje określają przepływ danych między narzędziami.
API wymaga przy tworzeniu zgłoszenia co najmniej jednego pola identyfikującego zgłaszającego, na przykład requester_id lub email. Pola status i priority mają wartości domyślne².

Jakie zadania działu IT można obsłużyć przez Freshdesk API?

Freshdesk API może przekazywać zgłoszenia pracowników między helpdeskiem a narzędziem IT i synchronizować zmiany w sprawach. Każda operacja powinna służyć konkretnemu celowi: rejestracji prośby, pobraniu kolejki albo aktualizacji obsługiwanego zgłoszenia.
Odpowiedź HTTP 201 Created potwierdza utworzenie zgłoszenia².

Jakie dane o zgłoszeniach i użytkownikach udostępnia API?

API pozwala pobierać zgłoszenia danego pracownika i wybierać sprawy według statusu, lecz żaden z tych warunków nie wskazuje kolejki zespołu IT. Identyfikator zgłaszającego wskazuje osobę, która przekazała sprawę, a status określa etap jej obsługi.
Wartość statusu 2 oznacza zgłoszenie otwarte².

Jak tworzyć, odczytywać i aktualizować zgłoszenia pracowników przez API?

Integracja powinna oddzielać tworzenie zgłoszeń przez POST, odczyt przez GET i aktualizację przez PUT². Taki podział zapobiega nadpisaniu danych podczas pobierania kolejki.

• Tworzenie zgłoszenia przekazuje do helpdesku dane pracownika i opis sprawy.
• Odczyt zgłoszeń odbywa się przez żądanie GET /api/v2/tickets.¹
• Aktualizacja zgłoszenia wskazuje konkretną sprawę oraz zmianę, którą narzędzie IT ma zapisać.

Jak filtrować wyniki, aby pobierać zgłoszenia właściwego zespołu IT?

Kolejkę IT wyznacza przypisanie zgłoszeń do zespołu, a nie sam identyfikator zgłaszającego czy status. API pozwala zawęzić odczyt według zgłaszającego lub statusu, natomiast grupę przypisaną do zgłoszenia identyfikuje osobne pole group_id². Dobór warunku zależy od tego, czy potrzebne są sprawy danej osoby, na określonym etapie obsługi czy przypisane do zespołu.

• Zgłoszenia pracownika pobiera parametr requester_id z identyfikatorem zgłaszającego.¹
• Zgłoszenia na określonym etapie wybiera parametr status.¹
• Pełny zbiór wyników wymaga obsługi paginacji, czyli pobierania kolejnych stron odpowiedzi. Bez tego kolejka może być niekompletna.¹

Kolejka IT powinna zawierać sprawy przypisane do zespołu, nie wszystkie zgłoszenia wybranego pracownika. Jedna strona wyników może zawierać maksymalnie 100 rekordów². Integracja musi pobierać kolejne strony, aby objąć całą kolejkę.

Webhooki i diagnostyka integracji Freshdesk API w dziale IT

Żądania do Freshdesk API trzeba wysyłać przez HTTPS, czyli szyfrowane połączenie sieciowe.¹ Przy diagnozowaniu usterki dział IT powinien osobno sprawdzić wysłanie żądania, odpowiedź API i zapis danych w narzędziu docelowym.
Webhook wysyła powiadomienie po zdarzeniu. Jego odbiornik musi sprawdzić poprawność danych przed ich zapisaniem³. Taki podział pomaga ustalić, na którym etapie pojawia się problem.

Co oznaczają błędy podczas wymiany danych ze zgłoszeniami IT?

Błąd autoryzacji oznacza, że integracja nie uzyskała dostępu do żądanej operacji. Klucze API mogą mieć różne uprawnienia. Przyczyną błędu bywa też nieprawidłowa konfiguracja lub kodowanie klucza.¹
Administrator powinien porównać uprawnienia użytego klucza z operacją wykonywaną przez narzędzie IT. Kod HTTP 403 oznacza odmowę dostępu, na przykład z powodu uprawnień agenta².

Jak przetestować przepływ danych między Freshdesk a narzędziem IT?

Test integracji Freshdesk powinien sprawdzić cały przepływ: wysłanie żądania, odpowiedź API i zapis w narzędziu IT. Odpowiedź HTTP 200 OK jest jednym z mierzalnych wyników udanego testu odczytu². Sama odpowiedź nie pokazuje jeszcze, czy dane trafiły do systemu docelowego.

• Żądanie testowe powinno dotyczyć zgłoszenia, które dział IT rozpozna po identyfikatorze.
• Kod statusu odpowiedzi API należy sprawdzić przed przetwarzaniem zwróconych danych.¹
• Wynik synchronizacji należy porównać ze stanem zgłoszenia w narzędziu IT.

Jak kontrolować wykorzystanie limitu żądań Freshdesk API?

Limit żądań Freshdesk API łatwiej kontrolować, gdy integracja rejestruje wywołania i rozróżnia odczyty od aktualizacji. Usuń odczyty, których wynik nie jest wykorzystywany. Błąd pojedynczego zgłoszenia nie powinien uruchamiać całej synchronizacji od nowa.
Dziennik pokaże, która operacja zwiększa liczbę żądań. Kod HTTP 429 sygnalizuje przekroczenie limitu; warto odróżnić go w dzienniku od błędów pojedynczych zgłoszeń².

Knit jako opcja integracji Freshdesk API z narzędziami IT

Knit jest opcją dla działu IT, który chce połączyć Freshdesk z innym narzędziem przez pośrednią warstwę integracyjną. Dział IT może też utrzymywać własne połączenie bezpośrednie.
Ujednolicone API zgłoszeniowe zapewnia wspólny sposób wymiany danych o sprawach między systemami. Przy ocenie Knit trzeba uwzględnić zakres danych, mapowanie statusów i odpowiedzialność za błędy synchronizacji. Pośrednia warstwa nie rozstrzyga, które zgłoszenia pracowników powinny trafić do narzędzia IT⁴.

Społeczność Freshworks przy rozwiązywaniu problemów integracyjnych

Społeczność Freshworks może pomóc w analizie integracji, jeśli opis wyraźnie oddziela działanie Freshdesk API od działania narzędzia IT. Warto wskazać operację, oczekiwany wynik i etap, na którym zatrzymuje się przepływ danych.
Przydatny będzie kod HTTP 400, oznaczający błędny format żądania lub błąd walidacji danych przesłanych do API².

Jak opisać problem z integracją, aby uzyskać pomoc w społeczności Freshworks?

Opis problemu w społeczności Freshworks powinien pozwalać odtworzyć błąd bez ujawniania danych pracowników i poświadczeń. Zgodnie z art. 5 ust. 1 lit. c RODO dane osobowe należy ograniczyć do niezbędnego minimum⁵. Lepiej więc opisać przebieg operacji i jej wynik niż podawać dane konkretnej osoby.

• Operacja integracyjna powinna być nazwana wraz z systemem wysyłającym żądanie i systemem odbierającym dane.
• Oczekiwany i rzeczywisty wynik powinny pokazywać, czy problem dotyczy odpowiedzi API, czy zapisu zgłoszenia w narzędziu IT.
• Przykład żądania i odpowiedzi powinien zachować istotne pola oraz kod statusu, ale pomijać klucz API i dane osobowe.

Dokładny opis pozwala innym uczestnikom skupić się na właściwym etapie integracji. Kod HTTP 404 przy odczycie może na przykład oznaczać, że zgłoszenie o podanym identyfikatorze nie istnieje².

Pobieranie danych Freshdesk do REST API Modular Input

REST API Modular Input może pobierać zgłoszenia z Freshdesk, jeśli w konfiguracji podano adres instancji i klucz API. Adres firmowej instancji nie jest wspólny dla wszystkich użytkowników.
Konfiguracja powinna ograniczać pobieranie do spraw potrzebnych działowi IT³. Zakres danych wynika wtedy z celu integracji, a nie z możliwości samego narzędzia.

Gdzie znaleźć klucz API potrzebny do połączenia z Freshdesk?

Klucz API Freshdesk znajduje się w profilu użytkownika, w sekcji klucza API. Należy go przechowywać w ustawieniach dostępu integracji, nie w publicznym opisie połączenia.
Uprawnienia konta, do którego należy klucz, powinny odpowiadać danym pobieranym przez REST API Modular Input. W API v2 klucz pełni funkcję loginu w uwierzytelnianiu HTTP Basic, a hasłem może być dowolny ciąg znaków².

Najczęściej zadawane pytania

Czy samo posiadanie konta Freshdesk wystarczy, aby korzystać z API?

Nie. Konto Freshdesk musi mieć włączony dostęp do API.

Czy adres instancji Freshdesk jest taki sam dla wszystkich firm?

Nie. Każda firmowa instancja ma własny adres.

Jaką rolę pełni klucz API w uwierzytelnianiu Freshdesk API v2?

W uwierzytelnianiu HTTP Basic klucz API pełni funkcję loginu, a hasłem może być dowolny ciąg znaków.

Jakiego pola nie może zabraknąć przy tworzeniu zgłoszenia?

Co najmniej jednego pola identyfikującego zgłaszającego, na przykład requester_id lub email.

Co powinien zrobić odbiornik webhooka przed zapisaniem otrzymanych danych?

Sprawdzić, czy dane są poprawne.