Qu’est-ce que l’API Zendesk ?
Une API, ou interface de programmation d’application, est un outil pour les applications logicielles. Dans un restaurant, un serveur apporte les plats de la cuisine à votre table. L’API a un fonctionnement similaire : elle transporte les données d’un point à un autre. Dans l’API, le plat s’appelle une ressource et le serveur qui vous l’apporte s’appelle un point de terminaison. Pensez à un plat spécifique que vous pourriez commander au restaurant. Certains points de terminaison vous apportent une gamme d’éléments, comme une assiette de dégustation. Un exemple dans l’API est le point de terminaison Liste des utilisateurs. Il renvoie la liste de tous les utilisateurs de votre compte Zendesk Support. Certains points de terminaison, comme le point de terminaison Afficher l’utilisateur sont plus spécifiques et ne renvoient qu’un seul élément.
Vous pouvez aussi utiliser l’API pour modifier certaines choses dans Zendesk. Imaginez que vous dites au serveur quelle cuisson vous voulez pour votre steak. Le chef modifie le steak pour le cuire à votre goût. L’API est une ressource puissante que beaucoup de nos clients utilisent pour importer des ressources en masse, créer des applications, exporter des données vers des sources externes, etc.
La majorité de la documentation de référence pour l’API Zendesk est disponible dans la section de référence pour les API du portail des développeurs Zendesk. La documentation de référence décrit tous les points de terminaison disponibles. Le guide pour les développeurs Zendesk peut aussi vous aider à vous lancer. La documentation est très complète, mais dans cet article, nous expliquerons comment les décoder et les utiliser.
Pourquoi utiliser l’API ?
Maintenant que vous savez ce qu’est l’API, vous vous demandez peut-être « Et alors ? ». En quelques mots, vous pouvez utiliser l’API pour ajouter des fonctionnalités qui ne sont pas disponibles dans l’interface utilisateur (que ce ne soit pas du tout ou simplement dans votre édition) beaucoup plus rapidement que si vous le faisiez entièrement « à la main ».
Pour les comptes avec l’édition Essential ou Team, l’API vous offre une méthode directe d’exportation de vos données sans avoir à mettre à niveau vers Professional (qui autorise les exportations de données automatisées). De la même façon, vous pouvez utiliser l’API pour obtenir des données de ticket à des fins de rapports. L’API peut renvoyer toutes les informations associées à un ticket et vous pouvez donc l’utiliser pour transférer des données à une application de rapports tierce.
Un autre avantage de l’API est de pouvoir mettre à jour de nombreux enregistrements rapidement. Par exemple, vous ne pouvez créer qu’une seule organisation à la fois dans l’interface d’agent, mais vous pouvez créer jusqu’à 100 organisations à la fois avec l’API. De façon similaire, vous pouvez mettre plus d’éléments à jour à la fois avec l’API. L’interface vous permet de modifier 60 tickets à la fois, l’API jusqu’à 100.
D’autres tâches courantes incluent :
- Création de tickets
- Migration des données dans Zendesk à partir d’un autre système
- Modification des utilisateurs en masse
- Recherche d’enregistrements
- Et bien plus...
Maintenant que nous avons vu ce à quoi peut vous servir l’API, passons à la façon de faire une demande API.
Format
L’API Zendesk renvoie les données dans un format léger appelé JSON. Consultez Utilisation de JSON dans le centre d’aide Zendesk. Vous pouvez voir les données formatées dans un navigateur Web en installant une extension d’affichage JSON pour Chrome ou Firefox.
JSON ressemble à ce qui suit :
{
"posts": [
{
"id": 35467,
"title": "How do I open the safe"
},
{
"id": 35468,
"title": "How do I reset the combination?"
},
]
}Un point de terminaison type ressemble à ce qui suit :
subdomain.zendesk.com/api/v2/users/me.json
Les points de terminaison peuvent effectuer les actions suivantes :
- GET - Récupérer des éléments
- POST - Créer des éléments qui n’existaient pas auparavant
- PUT - Mettre à jour des éléments existants
- DELETE - Supprimer des éléments
Dans un navigateur, vous pouvez uniquement faire des demandes GET. Vous pouvez effectuer les autres actions en utilisant des outils comme cURL ou Postman.
cURL
La documentation de référence utilise cURL dans tous les exemples de points de terminaison. cURL est un outil de ligne de commande qui vous permet d’essayer des commandes d’API sans navigateur. Pour en savoir plus, consultez Installation et utilisation de cURL dans le centre d’aide Zendesk. Vous pouvez utiliser cURL pour les 4 types d’appels. cURL est préinstallé sur les Mac, mais vous devrez l’installer pour Windows. Pour en savoir plus, consultez Installation de cURL dans le Center d’aide Zendesk.
Statut de vos demandes
Pour chaque demande API que vous faites, vous recevez une réponse vous indiquant si elle a marché ou non. Si elle n’a pas marché, la réponse vous donnera des indices vous permettant de comprendre pourquoi. Ces réponses s’appellent des codes de statut. Voici quelques-uns des plus courants :
- 200 - La demande a réussi
- 400 - La demande a échoué
- 409 - Erreur de fusion ou de contrainte, essayez à nouveau
- 422 - Entité impossible à traiter
- 429 - Limite de débit dépassée
- 500 - Avertissement ou état temporaire, contactez l’assistance si le problème persiste
Consultez la section sur le format des réponses dans la documentation de l’API pour en savoir plus au sujet des codes de statut.
Pratique
Maintenant que nous avons vu les bases de l’API, utilisons-la pour effectuer une recherche dans nos tickets.
Supposons que je suis un utilisateur avec l’édition Team et que j’utilise les marqueurs pour suivre le moment où les tickets sont transférés à différents niveaux d’assistance. J’ai ajouté les marqueurs escalation_one et escalation_two.
Je veux maintenant générer un rapport sur chaque ticket de mon système qui a subi ces deux transferts. J’ai essayé de créer une vue pour renvoyer ces tickets, mais cela n’a pas répondu à mes besoins car elle n’affichait pas les tickets archivés. Que faire maintenant ?
Réponse : utiliser l’API I pour récupérer les tickets.
Pour ce faire, vous aurez besoin du point de terminaison API de recherche. Ce point de terminaison ne filtre pas les tickets archivés, vous pouvez donc l’utiliser pour renvoyer une liste de tous les tickets qui incluent ces deux marqueurs. De façon similaire, l’API de recherche est un simple appel GET et vous pouvez donc l’utiliser directement dans votre navigateur si vous êtes connecté à votre Zendesk Support dans un autre onglet de votre navigateur. Le format du point de terminaison de recherche est le suivant :
subdomain.zendesk.com/api/v2/search.json?query={search_string}
Important : n’oubliez pas de remplacer sous_domaine par le sous-domaine de votre compte.
L’API de recherche est très souple et la requête peut utiliser n’importe quel élément décrit dans Recherche Zendesk - Principes de base. Dans notre exemple, comme nous cherchons simplement des marqueurs, le seul paramètre que nous utiliserons dans notre chaîne de recherche est « tags ». Pour rechercher plusieurs marqueurs, il suffit d’ajouter une virgule entre les marqueurs, après le paramètre « tags ». Votre appel devrait maintenant ressembler à ce qui suit :
https://subdomain.zendesk.com/api/v2/search.json?query=tags:escalation_one,escalation_two
Pour authentifier la demande, vous devez être un agent ou un administrateur connecté à Zendesk Support dans un autre onglet de votre navigateur.
En exécutant cet appel dans votre navigateur, vous recevrez une liste des tickets avec ces deux marqueurs. Vous pouvez alors enregistrer la sortie JSON pour une utilisation ultérieure.
Félicitations ! Vous êtes arrivé au bout. L’API est un outil puissant qui peut être utilisé de nombreuses façons différentes. Pour en savoir plus, consultez la documentation de référence et la documentation pour les développeurs Zendesk.