Comment supprimer un rôle dans Zoho Desk

La suppression d'un rôle dans Zoho Desk s'effectue via un unique appel API authentifié ciblant le rôle par son identifiant unique. Voici tout ce dont vous avez besoin pour que l'opération se déroule correctement.

Pourquoi c'est important

La gestion des rôles est au cœur du contrôle de ce que vos agents Zoho Desk peuvent voir et faire. Au fil du temps, les organisations accumulent des rôles redondants ou obsolètes qui encombrent la configuration et sèment la confusion chez les administrateurs. Savoir comment les supprimer par programmation — plutôt que de les chercher dans l'interface — fait gagner du temps et maintient votre configuration ordonnée, notamment lorsque vous gérez des rôles à grande échelle via l'automatisation ou des intégrations.

> Remarque : Beam Help est un service d'assistance expert indépendant pour Zoho — nous ne sommes pas le support officiel de Zoho.

---

Étape par étape

Étape 1. Vérifiez que vous disposez des bons scopes OAuth.

Avant d'effectuer un appel API, assurez-vous que votre token OAuth Zoho Desk connecté inclut les autorisations nécessaires. Le scope requis pour les opérations au niveau des paramètres (qui inclut la gestion des rôles) est Desk.settings.DELETE — ainsi que les scopes associés tels que Desk.settings.READ et Desk.settings.ALL pour un accès plus large. ^[3]

Étape 2. Récupérez le role_id que vous souhaitez supprimer.

Vous ne pouvez pas supprimer un rôle sans connaître son identifiant exact. Utilisez une requête GET sur l'endpoint des rôles (ou consultez votre panneau d'administration Zoho Desk) pour lister les rôles existants et noter le role_id de celui que vous souhaitez supprimer. Conservez cette valeur — vous la passerez directement dans l'appel de suppression.

Étape 3. Effectuez la requête DELETE.

Envoyez une requête DELETE vers l'endpoint suivant, en remplaçant l'identifiant réel du rôle à la place de {role_id} : ^[1]

DELETE /api/v1/roles/{role_id}

L'opération s'appelle deleterole et accepte roleid comme paramètre de chemin principal, avec un paramètre optionnel p pour d'éventuelles options de requête supplémentaires. ^[1]

Étape 4. Utilisez le helper client Python (le cas échéant).

Si vous travaillez avec une intégration basée sur Python, l'appel correspond à une méthode client simple. Passez le role_id sous forme de chaîne de caractères, et fournissez éventuellement un dictionnaire pour le paramètre p : ^[1]

def delete_role(self, role_id: str, p: dict = None):
    return self.c.request("DELETE", f"/api/v1/roles/{role_id}", p, None)

Étape 5. Initialisez le client Desk avec le bon org_id.

Les appels à l'API Zoho Desk nécessitent que l'identifiant de votre organisation soit défini sur le client. Lors de la création de l'instance ZohoDeskClient, passez le orgid avec votre domaine API et votre token d'accès. Si le orgid n'est pas encore enregistré, le client peut le découvrir automatiquement en appelant l'endpoint des organisations et en conservant le premier résultat. ^[6]

Étape 6. Gérez le renouvellement du token de manière proactive.

Les tokens d'accès expirent. Encapsulez votre appel de suppression dans un flux qui vérifie la validité du token et le renouvelle à l'aide du refreshtoken stocké avant l'envoi de la requête. Une fonction tokenrefresher doit récupérer le dernier refresh token depuis votre stockage de données, appeler l'endpoint de renouvellement OAuth, et mettre à jour le access_token stocké ainsi que l'horodatage d'expiration. ^[6]

---

Erreurs courantes

• Mauvais endpoint produit. Zoho CRM dispose également d'un endpoint de suppression de rôle (DELETE /Contacts/roles/{roleid}), mais celui-ci concerne les *rôles de contact de transaction* dans CRM — et non les rôles d'agents Desk. ^[2] Assurez-vous de cibler /api/v1/roles/{roleid} et d'utiliser un client authentifié Desk, et non un client CRM. ^[1]

• orgid manquant ou expiré. Zoho Desk exige l'identifiant de l'organisation pour chaque requête. Si le orgid est vide ou obsolète, l'API rejettera l'appel. Vérifiez toujours qu'il est renseigné avant d'exécuter la suppression. ^[6]

• Scope OAuth insuffisant. Si votre token a été généré sans Desk.settings.DELETE (ou le scope plus large Desk.settings.ALL), l'API retournera une erreur d'autorisation. Régénérez votre token en incluant le groupe de scopes de paramètres complet. ^[3]

• Suppression d'un rôle auquel des agents sont encore assignés. L'API peut refuser de supprimer un rôle auquel des agents actifs sont rattachés. Réassignez ou retirez ces agents du rôle avant de tenter la suppression.

---

Ce qu'il faut vérifier

• Couverture des scopes : Confirmez que votre token OAuth actif inclut Desk.settings.DELETE ou Desk.settings.ALL avant d'appeler l'endpoint. ^[3]
• Endpoint et client corrects : Vérifiez que vous appelez /api/v1/roles/{roleid} via une instance ZohoDeskClient — et non un client CRM — et que le orgid est renseigné. ^[1][6]
• Le rôle n'apparaît plus : Après un DELETE réussi, effectuez un GET sur la liste des rôles pour confirmer que le rôle a bien été supprimé et qu'aucun agent ne se retrouve inopinément sans attribution de rôle.