Ce que l’API TOPdesk renvoie, et ce qu’elle ne renvoie pas

La documentation officielle de l’API TOPdesk se trouve sur developers.topdesk.com. Elle est soignée, et l’API fonctionne comme prévu. Certaines particularités n’apparaissent pourtant qu’à l’usage, et elles peuvent vous amener à revoir en profondeur vos projets de reporting. Les points ci-dessous ont été relevés lors de la construction d’un tableau de bord alimenté par cette API.

Les données faciles à obtenir

Les incidents sont les plus simples à récupérer. Vous les obtenez avec leur catégorie et sous-catégorie, statut, priorité, niveau, groupe de spécialistes, spécialiste, date de création, dates de résolution et de clôture, et les champs SLA. Vous pouvez ainsi suivre le flux entrant, le temps de résolution et le respect des SLA par priorité, et calculer l’âge du plus ancien incident encore ouvert.

L’API fournit aussi les changements et leurs activités, les activités opérationnelles, les biens avec leur type, leur lieu et leur statut, et les éléments de connaissances avec leur statut et leur visibilité dans le Portail Utilisateurs. Les spécialistes peuvent être récupérés avec leurs groupes de permissions, qui vous indiquent quels comptes utilisent une licence payante. Les groupes de permissions ne disent pas, en revanche, si un tel compte est réellement utilisé ; pour le savoir, il faut rassembler des données de plusieurs modules.

Ce que l’API REST ne renvoie pas : l’historique

L’historique est le point essentiel, et celui qui pose problème dans la plupart des projets. L’API REST vous donne l’état actuel d’un incident, au moment où vous posez la question. Vous voyez son statut et le groupe de spécialistes auquel il est affecté, et vous savez chez qui il se trouve.

En revanche, vous ne voyez pas par où l’incident est passé. Vous ne pouvez pas demander à l’API si l’incident 4711 est d’abord passé par le premier niveau, puis est resté onze jours chez l’équipe réseau, avant de revenir. Ces transferts figurent bien dans TOPdesk, dans l’onglet Historique de la fiche, mais, au moment de la rédaction (septembre 2026), l’API REST ne les restitue pas.

Votre reporting ne peut donc pas montrer où le travail se bloque si vous vous limitez à l’API REST. La direction attend pourtant généralement cette information, car c’est à ces endroits que le temps de résolution s’allonge.

Avec l’API REST, la seule solution consiste à suivre l’historique vous-même, et votre chronologie ne commence alors qu’au moment où vous mettez en place la connexion. Vous ne pourrez pas la reconstituer après coup pour la période antérieure. Si vous avez besoin de cet historique, commencez donc tôt, car il devient plus utile à mesure que la période couverte s’allonge.

Les points de terminaison varient selon la licence et la version

L’API des incidents est la même partout. Pour les changements, les biens et les éléments de connaissances, les points de terminaison disponibles dépendent des modules compris dans votre licence et de votre version de TOPdesk.

Ne supposez donc pas qu’un point de terminaison existe. Si un environnement n’a pas de Gestion des biens, le point de terminaison des biens n’existe pas, et vous obtenez une erreur au lieu d’une liste vide. Vérifiez d’abord dans votre propre environnement quels points de terminaison sont disponibles, plutôt que de vous fier à la documentation générale.

La différence entre 401 et 403

Si vous distinguez bien ces deux codes, vous pouvez gagner des heures de recherche. Un 401 signifie que TOPdesk refuse l’authentification. La cause peut être un mauvais nom d’utilisateur, un jeton d’application révoqué (dans les anciennes versions de TOPdesk, un mot de passe d’application) ou un compte sans l’autorisation API REST. Un 403 signifie que vos identifiants sont corrects, mais que le spécialiste n’a pas de droits de lecture sur ce module.

En cas de 403, inutile donc de remplacer le jeton d’application. Allez dans les groupes de permissions de ce spécialiste et regardez quel module manque. Pendant le développement d’AureaDesk, les deux codes ont été confondus une fois, ce qui a coûté un après-midi.

La pagination dans les grands environnements

La pagination ne pose pas de problème visible sur un environnement de quelques milliers d’incidents. Sur les environnements volumineux et très sollicités, elle se comporte parfois autrement qu’un petit test ne le laisse prévoir. Le traitement se bloque alors, ou des enregistrements vous échappent sans que vous vous en aperceviez.

Ne testez pas uniquement sur votre propre environnement. Ce qui fonctionne sur quelques centaines d’incidents peut se comporter autrement sur des dizaines de milliers, et vous risquez de ne le découvrir que tardivement.

Attendez-vous aussi à ce que la première récupération complète soit plus lourde que prévu. Sur un petit serveur, l’extraction d’une grande liste en une seule opération atteint les limites de mémoire. Répartissez donc la récupération en plusieurs lots.

Ce dont vous avez besoin pour vous connecter

Au moment de la rédaction de cet article, vous n’avez pas besoin d’une licence d’intégration spéciale ; vérifiez-le dans votre propre contrat TOPdesk. Vous créez dans TOPdesk un compte API, c’est-à-dire un spécialiste réservé à la connexion, avec un accès API et des droits de lecture sur les modules à consulter. Vous créez pour lui un jeton d’application, que votre connexion utilisera.

Utilisez un spécialiste dédié plutôt que le compte d’un collègue. Dans les journaux, vous voyez ainsi clairement que l’action vient de la connexion et non d’une personne. Vous pouvez aussi désactiver la connexion quand vous le souhaitez, sans priver qui que ce soit de son propre accès.

Limitez les droits au strict nécessaire. Le reporting n’a pas besoin d’un accès en écriture aux données, et une connexion en lecture seule ne peut rien modifier dans votre TOPdesk. Comme la connexion passe par l’API, signalez-la à la personne qui gère votre TOPdesk.

Un tableau de bord sur l’API REST

L’API REST permet de bâtir un tableau de bord à part entière, mais il faut y consacrer plus de temps que ne le laisse croire un premier essai. Si vous voulez savoir où le travail se bloque, vous devez suivre l’historique vous-même. Vérifiez aussi dans chaque environnement ce qui est disponible, au lieu de vous fier à la documentation générale. Après chaque nouvelle version de TOPdesk, contrôlez à nouveau quels points de terminaison existent.