Zendesk-kompatible API

Viele Teams haben eigene Systeme, die mit der Zendesk-API sprechen: interne Dienste mit den offiziellen SDKs, Backoffice-Werkzeuge, FAQ-Widgets auf anderen Websites. HelpFalcon beantwortet diese Anfragen unter /zd/api/v2 mit denselben Anfrage- und Antwortformaten, sodass sich nur die Basis-URL und der API-Token ändern.

Schreibzugriffe auf Tickets laufen durch die normale Ticket-Pipeline: ein Audit pro Anfrage, Trigger und SLAs laufen, und der Audit-Akteur ist der Besitzer des Tokens.

Einen Client umstellen

1. Erstellen Sie unter Admin Center, Integrations, API tokens einen API-Token für den Integrationsnutzer, mit dem Scope write.
2. Richten Sie den Client auf Ihren Workspace aus:

Client	Einstellung
Einfaches HTTP	Basis-URL https://yourcompany.helpfalcon.com/zd/api/v2
C# ZendeskApi.Client	Subdomain yourcompany.helpfalcon.com/zd, Benutzername {email}/token, der HelpFalcon-Token
C# ZendeskApi_v2	new ZendeskApi("https://yourcompany.helpfalcon.com/zd/api/v2", email, token)
PHP zendesk_api_client_php	$client->setApiBasePath('zd/api/v2/') und Ihr Workspace-Host
Hilfe-Center-Leser	Basis-URL https://yourcompany.helpfalcon.com/zd

3. Authentifizieren Sie sich wie bisher: Basic {email}/token:{token}, Authorization: Bearer {token} oder OAuth Client Credentials unter POST /zd/oauth/tokens mit client_id = E-Mail des Token-Besitzers und client_secret = der Token. Passwort-Authentifizierung wird nicht unterstützt.

Jeder .json-Pfad antwortet auch ohne .json. Links der Form {BaseUrl}agent/tickets/{id} leiten zum Ticket im Agent-Workspace weiter.

IDs

Importierte Datensätze behalten ihre Zendesk-IDs: Ticketnummern sowie Nutzer-, Organisations-, Gruppen- und Hilfe-Center-IDs. In HelpFalcon angelegte Datensätze erhalten neue IDs oberhalb der höchsten importierten.

Endpunkte

Bereich	Endpunkte
Tickets	GET/POST tickets, GET/PUT/DELETE tickets/{id}, GET tickets/show_many, PUT tickets/update_many, DELETE tickets/destroy_many, GET tickets/count, GET tickets?external_id=
Kommentare und Audits	GET tickets/{id}/comments, GET tickets/{id}/audits, GET tickets/{id}/audits/{audit_id}
Tags	GET/POST/PUT/DELETE tickets/{id}/tags
Uploads	POST uploads?filename= (der Token hängt Dateien an den nächsten Kommentar)
Jobs	GET job_statuses/{id} für Massenaktualisierungen und -löschungen
Suche	GET search, GET search/count, mit der Zendesk-Suchsyntax
Inkrementeller Export	GET incremental/tickets/cursor, GET incremental/users/cursor und die zeitbasierten Varianten
Nutzer	GET/POST users, GET users/{id}, GET users/me, POST users/create_or_update, GET users/search
Organisationen, Gruppen	GET organizations, GET organizations/{id}, GET groups, GET groups/{id}
Hilfe-Center (öffentlich)	GET help_center/{locale}/sections, .../sections/{id}/articles, .../articles/{id}, GET help_center/articles/search

Massenoperationen liefern wie bei Zendesk einen Job. Konkurrierende Aktualisierungen mit safe_update liefern 409.

Wie stabil das ist

Die Formate auf dieser Seite sind eingefroren: Wir fügen hier nur Endpunkte und Felder hinzu und ändern nie eine Antwort, die ein für Zendesk geschriebener Client auswertet. Nichts wird mit weniger als 12 Monaten Vorlauf entfernt. Siehe Versionierung und Abkündigung.

Was nicht mit einer Basis-URL umzieht

Integrationen, die Sie nicht selbst geschrieben haben und die fest auf *.zendesk.com verdrahtet sind (zum Beispiel die Zendesk-App für Zapier, der Zendesk-Connector von Fivetran oder die Zendesk-Mobile-SDKs), lassen sich nicht auf HelpFalcon umstellen. Nutzen Sie stattdessen die REST-API, Webhooks oder den Messenger. Siehe Wechsel von Zendesk.

Zendesk ist eine Marke von Zendesk, Inc. HelpFalcon ist nicht mit Zendesk, Inc. verbunden und wird von Zendesk, Inc. weder unterstützt noch gesponsert; die kompatible API dient der Interoperabilität mit Ihrer eigenen Software.