Zendesk — konfiguracja, integracje

Zendesk API pozwala połączyć Zendesk z systemami działu IT i wymieniać dane o zgłoszeniach pracowników. W artykule omawiamy planowanie takiego połączenia, uwierzytelnianie, diagnostykę automatyzacji oraz warunki dla twórców integracji.
Już na etapie planowania trzeba uwzględnić limit planu Zendesk Suite Professional: 400 żądań Support API na minutę¹.

Czym jest Zendesk API w obsłudze danych i zgłoszeń IT?

System pracowniczy może przekazać przez Zendesk API zgłoszenie awarii sprzętu do działu IT. Dokumentacja Zendesk APIs obejmuje 7 obszarów: Ticketing, Help Center, Voice, Live Chat, Sales CRM, Custom Data i Conversations (Messaging)². W Ticketing API zasób tickets przechowuje zgłoszenia, a users – dane użytkowników, w tym pracowników³.

Dział IT powinien zacząć od Ticketing, czyli obsługi zgłoszeń. Pozostałe obszary mają znaczenie zależnie od kanałów kontaktu i danych używanych przez pracowników. Przed połączeniem systemów trzeba ustalić, gdzie znajdują się źródłowe dane pracownika i jak rozpoznać tę samą sprawę po obu stronach.
Pole id nadaje zgłoszeniu Zendesk, a external_id pozwala powiązać je z identyfikatorem sprawy w systemie zewnętrznym⁴.

Tabela zestawia 7 obszarów dokumentacji Zendesk API: Ticketing, Help Center, Voice, Live Chat, Sales CRM, Custom Data i Conversations, wraz z rodzajami danych przydatnych w obsłudze pracowników².

Jak wysłać żądanie z systemu pracowniczego i odczytać odpowiedź API?

System pracowniczy wysyła przez Zendesk API żądanie dotyczące zgłoszenia, a odpowiedź wykorzystuje w dalszej obsłudze sprawy. Przy pomyślnym utworzeniu zgłoszenia żądaniem POST interfejs zwraca kod HTTP 201 Created³.

• Cel żądania musi wskazywać określoną operację, na przykład odczyt zgłoszenia awarii. Do takiego odczytu system pracowniczy potrzebuje identyfikatora właściwej sprawy.
• Żądanie HTTPS musi trafić pod adres interfejsu właściwy dla operacji i zawierać wymagane dane uwierzytelniające. Dane pracownika należy przesłać tylko wtedy, gdy operacja ich wymaga.
• Odpowiedź API trzeba odczytać przed zapisaniem zmian w systemie pracowniczym. Integracja powinna osobno obsługiwać otrzymane dane, brak dostępu i niepowodzenie operacji.

System pracowniczy otrzymuje wynik określonej operacji. Samo wysłanie żądania nie dowodzi, że się powiodła.
Kod 201 potwierdza utworzenie zgłoszenia, natomiast 422 oznacza, że poprawne składniowo żądanie nie może zostać przetworzone⁵.

Jak powiązać zgłoszenia IT z użytkownikami i organizacjami?

Integracja musi konsekwentnie przypisywać zgłoszenie do pracownika i właściwej organizacji. Dzięki temu agent IT wie, kogo dotyczy sprawa. W zgłoszeniu pole requester_id wskazuje zgłaszającego, a organization_id – powiązaną z nim organizację⁴.

• Pracownik powinien mieć jednoznaczny identyfikator używany przez integrację. Adres mailowy może pomóc w wyszukaniu osoby, ale po powiązaniu system powinien zachować identyfikator rekordu.
• Organizacja powinna odpowiadać strukturze obsługi przyjętej w firmie, na przykład spółce albo jednostce organizacyjnej. Przy kolejnych zgłoszeniach tego pracownika integracja musi stosować tę samą regułę przypisania.
• Powiązanie zgłoszenia trzeba zapisać po utworzeniu sprawy. Zachowany identyfikator pozwoli później zaktualizować zgłoszenie bez tworzenia kolejnego dla tej samej awarii.

Stałe identyfikatory wiążą historię obsługi IT z właściwym pracownikiem. To ważne także przy kolejnych sprawach tej osoby.
Wartość external_id użytkownika musi być unikalna w ramach konta Zendesk, co pomaga utrzymać to powiązanie⁶.

Jak prowadzić zgłoszenie od utworzenia do zamknięcia przez integrację?

Zendesk API może obsługiwać cały cykl życia zgłoszenia IT. Integracja musi przy tym zachować identyfikator sprawy i synchronizować zmiany jej stanu. Może uwzględniać 6 standardowych statusów: new, open, pending, hold, solved i closed; dostępność hold zależy od konfiguracji konta⁴.

• Utworzenie zgłoszenia powinno przekazać opis problemu i dane osoby zgłaszającej. System źródłowy musi następnie zapisać otrzymany identyfikator sprawy.
• Aktualizacja zgłoszenia powinna korzystać z zapisanego identyfikatora. Informacje o wykonanych czynnościach pomagają agentowi odtworzyć przebieg naprawy.
• Zamknięcie zgłoszenia powinno przebiegać zgodnie z procesem obsługi IT przyjętym w firmie. Integracja musi odnotować końcowy stan również w systemie pracowniczym.

Wspólny identyfikator zachowuje ciągłość obsługi od zgłoszenia problemu do zakończenia sprawy. Przy zmianie stanu znaczenie ma także możliwość powrotu do pracy nad zgłoszeniem.
Zgłoszenie solved można ponownie otworzyć, lecz zgłoszenia closed nie można już otworzyć ponownie⁷.

Jak stronicować i filtrować dane na potrzeby działu IT?

Zendesk API pozwala pobierać dane partiami i ograniczać odczyt do spraw potrzebnych działowi IT⁸. Ma to znaczenie, gdy integracja regularnie odświeża zgłoszenia. Zakres pobieranych danych warto więc ustalić przed uruchomieniem synchronizacji.

• Filtr danych powinien wynikać z zadania integracji, na przykład obejmować sprawy obsługiwane przez IT. Osobne zapytania mogą pobierać bieżące zgłoszenia i sprawy archiwalne.
• Stronicowanie oznacza pobieranie kolejnych części wyniku, a nie uznanie pierwszej odpowiedzi za całą listę. Integracja powinna przechodzić między stronami w sposób przewidziany dla wybranego żądania.
• Synchronizacja musi zapamiętać punkt, od którego wznowi odczyt po przerwie. Przed ponownym zapisaniem rekordu system powinien rozpoznać, czy sprawę już przetworzył.

Filtr wyznacza sprawy potrzebne integracji, a stronicowanie pozwala odebrać cały wybrany zbiór. Oba mechanizmy pełnią więc różne zadania.
Przy stronicowaniu kursorem parametr page[size] określa wielkość strony; większość punktów końcowych dopuszcza maksymalnie 100 rekordów⁹.

Uwierzytelnianie i diagnostyka Zendesk API w dziale IT

Metodę uwierzytelniania trzeba dobrać do sposobu działania integracji. Dział IT powinien osobno diagnozować dane logowania, uprawnienia konta, treść żądania i tempo automatyzacji. Odpowiedź na każde żądanie pomaga ustalić, gdzie wystąpił problem.
Token API działa jak hasło przesyłane z danymi konta, natomiast OAuth 2.0 używa tokenu dostępu i jest metodą zalecaną przez Zendesk¹⁰.

Użytkownik społeczności Zendesk twierdzi, że tokeny API nie są przypisywane do konkretnego użytkownika ani ograniczane zakresem uprawnień. To relacja użytkownika, nie reguła bezpieczeństwa potwierdzona dokumentacją produktu¹¹. W tej samej dyskusji opisano zalecenie przedstawiciela Zendesk, by po rozważeniu OAuth korzystać z tokenów API; dotyczyło ono omawianego tam przypadku¹¹.

Tabela porównuje zadania działu IT przy wdrażaniu obu metod uwierzytelniania.

Jak odróżnić problem z uprawnieniami od błędnych danych w żądaniu?

Odpowiedź Zendesk API trzeba zestawić z wysłanym żądaniem i kontem używanym przez integrację. W diagnostyce 401 wskazuje problem uwierzytelniania, 403 brak uprawnień, 422 nieprzetwarzalne dane żądania, a 429 przekroczenie limitu żądań¹². Każdy z tych przypadków wymaga sprawdzenia innej części połączenia.

• Dane uwierzytelniające wymagają sprawdzenia sekretu i sposobu przekazania go w żądaniu¹³.
• Uprawnienia konta trzeba porównać z operacją wykonywaną przez integrację. Możliwość odczytania sprawy nie oznacza automatycznie prawa do jej zmiany.
• Dane żądania należy sprawdzić względem wymagań wybranej operacji. Dotyczy to między innymi identyfikatora zgłoszenia i nazw pól.

Oddzielne sprawdzenie tych przyczyn pomaga uniknąć zmiany uprawnień, gdy poprawy wymaga samo żądanie. Nie daje jednak gwarancji, że taka zmiana nigdy nie będzie potrzebna¹³.

Dlaczego automatyzacja IT może przekroczyć limit żądań?

Zendesk API może otrzymać zbyt wiele żądań, gdy jednocześnie działają synchronizacja pracowników, odczyt zgłoszeń i ponawianie nieudanych operacji. W planie Zendesk Suite Team limit Support API i Help Center API wynosi 200 żądań na minutę.
Po jego przekroczeniu interfejs zwraca odpowiedź 429¹.

Automatyzacja IT powinna ograniczać równoległe odczyty i pobierać tylko potrzebne dane. Po sygnale przekroczenia limitu musi też wstrzymać ponawianie żądań. Niekontrolowane próby zwiększają ruch zamiast przywracać synchronizację¹⁴.

Jak przetestować połączenie i dane uwierzytelniające przed uruchomieniem integracji?

Połączenie z Zendesk API warto najpierw sprawdzić operacją odczytu. Dopiero po takim teście system pracowniczy powinien zacząć tworzyć lub zmieniać zgłoszenia. Poprawnie uwierzytelnione żądanie GET /api/v2/users/me.json powinno zwrócić kod HTTP 200 i dane użytkownika⁶.

• Połączenie należy sprawdzić żądaniem HTTPS wysłanym ze środowiska, w którym będzie działać integracja.
• Uwierzytelnianie trzeba zweryfikować metodą i danymi dostępu przeznaczonymi dla uruchamianego połączenia.
• Odpowiedź należy zapisać razem ze statusem i komunikatem błędu. Tokeny i inne sekrety nie powinny trafiać do dziennika.
• Uprawnienia trzeba przetestować na operacji odpowiadającej zadaniom integracji. Przy zmianach w rzeczywistych zgłoszeniach należy zachować ostrożność.

Test powinien potwierdzić dostęp do właściwych danych oraz obsługę błędnych odpowiedzi. Samo nawiązanie połączenia nie wystarczy.
Sprawdź odpowiedź 200 dla poprawnego odczytu i rozróżniaj 401 przy błędnym uwierzytelnianiu oraz 403 przy braku uprawnień¹⁵.

Warunki prawne dla twórców integracji z Zendesk

Korzystanie z Zendesk API podlega Zendesk Developer Terms oraz zasadom zmian interfejsu – Change policy². Warunki deweloperskie dotyczą używania API. Zasady zmian mają z kolei znaczenie przy utrzymywaniu połączenia z systemem pracowniczym.

Dział IT powinien uwzględnić oba dokumenty, ustalając odpowiedzialność za rozwój i utrzymanie integracji. Zgodność obejmuje sposób korzystania z API oraz reagowanie na zmiany interfejsu.

Najczęściej zadawane pytania

Czy Zendesk ma API?

Tak. Zendesk API umożliwia połączenie Zendesk z systemami działu IT i wymianę danych o zgłoszeniach pracowników.

Czy dział IT musi korzystać ze wszystkich obszarów Zendesk API?

Nie. Zależnie od kanałów kontaktu i używanych danych dział IT może zacząć od Ticketing, a pozostałe obszary uwzględnić wtedy, gdy są potrzebne.

Czy status hold jest dostępny na każdym koncie Zendesk?

Nie zawsze — jego dostępność zależy od konfiguracji konta.

Czy zgłoszenie ze statusem closed można ponownie otworzyć?

Nie. Ponownie otworzyć można zgłoszenie solved, ale closed nie można już otworzyć.

Ceny i warunki sprawdzone u źródeł: październik 2026.