Comment lister les équipes associables dans Zoho Desk

Lister les équipes associables dans Zoho Desk est simple dès lors que vous savez quel endpoint d'API appeler et comment transmettre les bons paramètres. Cet article vous guide à travers le processus en utilisant l'API REST de Zoho Desk.

Pourquoi c'est important

Lorsque vous créez des intégrations ou des automatisations sur Zoho Desk, vous avez souvent besoin de savoir quelles équipes peuvent être associées à une ressource donnée — par exemple, lors du routage de tickets ou de l'affectation d'agents. L'endpoint « équipes associables » vous fournit une liste filtrée des équipes éligibles à l'association, ce qui est distinct du simple listage de toutes les équipes dans chaque département. Comprendre cette différence vous aide à éviter d'affecter des tickets à des équipes non éligibles et maintient vos workflows propres.

Étape par étape

Étape 1. Vérifiez que vos scopes OAuth sont correctement configurés avant d'effectuer tout appel API. Votre intégration Zoho Desk a besoin au minimum du scope Desk.basic.READ dans sa liste de scopes pour lire les données des équipes et des agents. Vérifiez votre configuration OAuth et assurez-vous que ce scope — ainsi que tous les autres requis par votre application — est bien présent. ^[5]

Étape 2. Effectuez une requête GET vers l'endpoint /api/v1/teams/associable. Il s'agit de l'opération dédiée à la récupération des équipes pouvant être associées, et elle accepte un dictionnaire de paramètres de requête optionnel (communément appelé p) pour le filtrage ou la pagination. ^[1]

GET /api/v1/teams/associable

En Python, l'appel ressemble à ceci :

result = desk_client.list_associable_teams(p={"limit": 20})

L'argument p est optionnel — omettez-le entièrement si vous souhaitez la réponse par défaut sans filtres supplémentaires. ^[1]

Étape 3. Si vous avez besoin d'une vue plus large — toutes les équipes de chaque département associé à votre compte — utilisez plutôt l'endpoint séparé GET /api/v1/teams. Cette opération, listteamsfromallassociated, retourne les équipes de tous les départements liés plutôt que seulement celles éligibles à l'association. ^[3]

GET /api/v1/teams

result = desk_client.list_teams_from_all_associated(p=None)

Utilisez cet endpoint lorsque vous souhaitez un inventaire complet des équipes, et l'endpoint associable lorsque vous devez restreindre les résultats aux équipes qui sont des cibles valides pour une action d'association. ^[3]

Étape 4. Si votre cas d'usage est spécifique à un agent — par exemple, vous souhaitez savoir à quelles équipes appartient déjà un agent particulier — il existe un troisième endpoint limité à un agent individuel. Envoyez une requête GET vers /api/v1/agents/{agentid}/teams, en remplaçant {agentid} par l'identifiant numérique ou textuel de l'agent concerné. ^[8]

GET /api/v1/agents/{agent_id}/teams

result = desk_client.list_associated_teams_of_agent(agent_id="98765", p=None)

Cela est utile pour auditer l'appartenance aux équipes ou pré-remplir des listes déroulantes d'interface filtrées selon le contexte d'un agent spécifique. ^[8]

Étape 5. Analysez la réponse. Les trois endpoints retournent leurs données via le même mécanisme de requête sous-jacent, de sorte que la structure de la réponse suivra l'enveloppe standard de l'API Zoho Desk. Parcourez la collection retournée pour extraire les identifiants d'équipes, les noms et tout autre attribut dont votre intégration a besoin. ^[1][3][8]

Erreurs courantes

• Scope Desk.basic.READ manquant. C'est la raison la plus fréquente pour laquelle ces endpoints retournent une erreur 401 ou 403. Vérifiez bien que Desk.basic.READ (et Desk.basic.CREATE si vous prévoyez d'écrire) est inclus dans votre chaîne de scopes OAuth. Un scope manquant bloquera silencieusement l'accès aux données des agents et des équipes, même si des scopes liés aux tickets sont présents. ^[5]

• Confusion entre « associable » et « toutes les équipes ». L'endpoint /api/v1/teams/associable est intentionnellement plus restrictif que /api/v1/teams. Si vous appelez le mauvais, vous risquez de voir trop peu d'équipes (et de manquer des options valides) ou trop (et d'autoriser des associations invalides). Faites correspondre l'endpoint à votre cas d'usage réel. ^[1][3]

• Oubli de l'orgid. Zoho Desk est multi-organisation. Si votre connexion n'a pas encore résolu le bon deskorg_id, les appels API peuvent retourner des données pour la mauvaise organisation ou échouer complètement. Assurez-vous que l'ID d'organisation est découvert et stocké avant d'effectuer des requêtes liées aux équipes. ^[4]

Ce qu'il faut vérifier

• Vérifiez que Desk.basic.READ apparaît dans votre configuration de scope OAuth active et que le token a été réémis après tout changement de scope. ^[5]
• Confirmez que la réponse de /api/v1/teams/associable retourne une liste non vide ; si elle est vide, vérifiez que votre compte dispose d'équipes configurées dans Zoho Desk et que le bon org_id est utilisé. ^[1][4]
• Si vous filtrez par agent, validez que l'agentid que vous transmettez à /api/v1/agents/{agentid}/teams est un identifiant d'agent valide et actif dans votre organisation Desk. ^[8]

---

*Beam Help fournit une assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Référez-vous toujours à la documentation officielle de Zoho pour les dernières modifications de l'API.*