Zendesk — konfiguracja, limity

Zendesk API umożliwia wymianę danych między platformą Zendesk a innymi systemami. Ten poradnik omawia obsługę zgłoszeń, żądania i błędy API, konfigurację kanałów, automatyzacje oraz integracje ze sklepem i CRM.
Wprowadzenie do dokumentacji wymienia siedem obszarów API Zendesk, wśród nich zgłoszenia, centrum pomocy i czat¹.

Czym jest Zendesk API i jakie są jego rodzaje?

Poszczególne interfejsy Zendesk API różnią się zasobami, które obsługują. API Reference dokumentuje te interfejsy; nie jest osobnym API.
Ścieżka żądania wskazuje, którego obszaru platformy dotyczy operacja².

Ścieżka /api/v2/community/topics prowadzi do tematów społeczności. Wybór interfejsu zacznij od zasobu, na przykład zgłoszenia lub tematu społeczności, a dopiero potem wybierz operację.
Przy stronicowaniu listy tematów pobierzesz maksymalnie 100 rekordów na stronę³.

Jakie obszary platformy obsługują poszczególne interfejsy Zendesk API?

Zendesk API pozwala wykonywać na tematach społeczności operacje GET, POST, PUT i DELETE⁴. W tym przypadku topic oznacza temat, a metoda żądania określa, co ma się z nim stać.
Po pomyślnym utworzeniu tematu API zwraca kod HTTP 201 Created⁴.

Tabela zestawia 4 metody HTTP używane przy tematach społeczności: GET, POST, PUT i DELETE⁴.

Ścieżka wskazuje zasób, a metoda – wykonywaną na nim operację.
Aktualizacja i usunięcie wymagają podania identyfikatora konkretnego tematu w ścieżce żądania⁴.

Zendesk API w praktyce: żądania, zgłoszenia, błędy i limity

Żądania Zendesk API kierujesz do zasobów platformy. Przy obsłudze zgłoszeń zaplanuj osobno uwierzytelnianie, operację na danych i sposób odczytania odpowiedzi. Zgłoszenie, czyli ticket, to rekord sprawy klienta.
Zanim zapiszesz wynik w sklepie lub CRM, odczytaj odpowiedź API. Nieudane żądanie nie oznacza zakończonej synchronizacji. Po utworzeniu zgłoszenia integracja może sprawdzić kod HTTP 201 Created przed zapisaniem jego identyfikatora⁵.

Token API i OAuth to sposoby uzyskania dostępu omawiane przez użytkowników Zendesk. Decyzję o sposobie dostępu podejmij niezależnie od wyboru operacji na zgłoszeniu.
Samo poprawne uwierzytelnienie nie oznacza jeszcze, że żądanie się powiodło⁶.

Jak wysłać żądanie do Zendesk API i odczytać odpowiedź?

Żądanie Zendesk API trafia do wybranego zasobu. O jego wyniku mówi odpowiedź serwera.
Pomyślny odczyt zgłoszenia metodą GET daje kod HTTP 200 OK⁷.

• Adres zasobu wskazuje dane, których dotyczy żądanie. Wybierz ścieżkę odpowiadającą planowanej operacji.
• Uwierzytelnienie określa podstawę dostępu. Dobierz je przed wysłaniem żądania.
• Odpowiedź zawiera status oraz dane albo opis błędu. Przed przetworzeniem wyniku odczytaj zarówno status, jak i treść.

Wynik żądania zapisz w integracji dopiero po ocenie odpowiedzi API. Sprawdź, czy kod należy do zakresu 2xx, czyli mieści się między 200 a 299⁷.

Jak tworzyć, odczytywać i aktualizować zgłoszenia przez Zendesk API?

Pracę ze zgłoszeniami najłatwiej podzielić według celu: utworzenia rekordu, pobrania danych lub zmiany istniejącej sprawy.
Celom tym odpowiadają kolejno metody HTTP POST, GET i PUT⁸.

• Tworzenie zgłoszenia polega na przekazaniu danych nowej sprawy do odpowiedniego zasobu. Zachowaj identyfikator z odpowiedzi, aby powiązać sprawę z rekordem w sklepie lub CRM.
• Odczyt zgłoszenia wymaga wskazania rekordu, którego dane mają trafić do integracji. Przed aktualizacją drugiego systemu sprawdź odpowiedź API.
• Aktualizacja zgłoszenia wymaga wskazania istniejącego rekordu oraz danych do zmiany. Dopiero po sprawdzeniu wyniku oznacz synchronizację jako zakończoną.

Wyszukiwanie zgłoszeń pozwala jednocześnie zawęzić wyniki według statusu i tagów. W dyskusji pojawiło się zapytanie do /api/v2/search.json z warunkami type:ticket, status<=closed, tags:check_for_migrated i tags:!GDPR⁹.
Taki filtr pomaga znaleźć określone sprawy, gdy nie odczytujesz zgłoszenia o znanym identyfikatorze. Search API zwraca maksymalnie 1000 wyników jednego zapytania, nawet jeśli dopasowań jest więcej¹⁰.

Jak rozpoznać błędy Zendesk API i na nie reagować?

Zendesk API sygnalizuje niepowodzenie w odpowiedzi na żądanie. Najpierw odczytaj status i treść błędu.
Kod HTTP 422 oznacza, że poprawnie sformułowanego żądania nie można przetworzyć; nie należy mylić go z błędem uprawnień⁷.

• Błąd dostępu wymaga sprawdzenia uwierzytelnienia i uprawnień użytych przy żądaniu. Ustal przyczynę odmowy, zanim ponowisz żądanie bez zmian.
• Błąd danych wymaga sprawdzenia zasobu i przesłanych pól. Popraw żądanie przed kolejną próbą⁷.
• Błąd synchronizacji wymaga zapisania statusu i treści odpowiedzi przy rekordzie integracji. Dzięki temu odróżnisz nieudaną operację API od błędu sklepu lub CRM.

W dyskusji społeczności użytkownik wyraził obawę o kontrolę dostępu przez tokeny API. Wskazał, że tokeny nie są przypisywane do konkretnej osoby i nie pozwalają określić zakresu jej uprawnień¹¹. Ten sam użytkownik relacjonował, że podczas wdrożenia przedstawiciel Zendesk zalecił mu token API zamiast przepływu OAuth.
To relacja z rozmowy, nie ogólna zasada wyboru uwierzytelnienia¹¹.

Tabela porównuje sposoby dostępu pod kątem zakresów uprawnień tokenów⁶.

Jak sprawdzić limity żądań i postępować po odpowiedzi 429?

Zendesk API odpowiada kodem 429 po przekroczeniu limitu żądań. Integracja powinna wtedy wstrzymać kolejne próby, zamiast od razu ponawiać żądanie.
W planie Zendesk Suite Team limit dla Support API i Help Center API wynosi 200 żądań na minutę¹².

• Status 429 wskazuje odpowiedź związaną z limitem. Zapisz go razem z nagłówkami odpowiedzi.
• Informacja o czasie oczekiwania określa termin ponowienia żądania, jeśli serwer ją przekazuje. Zaczekaj do tego terminu, zamiast wysyłać serię natychmiastowych prób.
• Kolejka żądań pozwala odłożyć niewykonane operacje. Wznów je po upływie czasu oczekiwania i ponownie sprawdź odpowiedź.

Obsługa limitu wymaga rozpoznania odpowiedzi 429, odłożenia żądań i ponowienia ich we właściwym czasie. Czas ten wynika z odpowiedzi serwera.
W przykładzie Zendesk nagłówek Retry-After przy błędzie 429 nakazuje odczekać 93 sekundy¹³.

Warunki prawne korzystania z Zendesk API

Z Zendesk API korzystaj zgodnie z warunkami umowy dotyczącymi usługi i zasadami ochrony danych właściwymi dla danej integracji.
Obowiązki zależą od tego, jakie dane przepływają między Zendesk a sklepem, CRM lub innym systemem¹⁴.

Dane osobowe przekazywane przez API podlegają przepisom o ochronie danych, w tym RODO. Firma powinna określić cel ich przekazywania i ograniczyć zakres informacji do tego celu.
Jeśli integracja przenosi treść zgłoszeń, trzeba uwzględnić również dane wpisywane przez klientów w wiadomościach¹⁵.

Dostęp do integracji powinien wynikać z zadań systemu korzystającego z API. Zasady przechowywania i usuwania danych oraz reagowania na incydenty muszą obejmować cały przepływ informacji, nie tylko połączenie z Zendesk.
Gdy zgłoszenie jest wymagane, art. 33 RODO przewiduje dla administratora termin, w miarę możliwości, 72 godzin od stwierdzenia naruszenia¹⁶.

Warunki umowy i zasady ochrony danych wyznaczają sposób, w jaki można korzystać z Zendesk API.

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