Comment obtenir le formulaire pendant la transition dans Zoho Desk

Récupérer le formulaire « pendant la transition » d'un ticket Zoho Desk vous permet d'inspecter précisément quels champs sont présentés à un agent lorsqu'il fait passer un ticket par une transition de workflow spécifique — une étape clé avant d'automatiser ou de valider la logique de transition.

Pourquoi c'est important

Les transitions de workflow Zoho Desk peuvent afficher des formulaires personnalisés en cours de processus, collectant des données supplémentaires auprès des agents avant qu'un changement de statut ne soit validé. Si vous construisez une intégration, auditez votre processus de support, ou cherchez à comprendre pourquoi une transition se comporte de manière inattendue, vous devez récupérer cette définition de formulaire par programmation. Comprendre la structure du formulaire vous aide également à pré-remplir ou valider les valeurs des champs dans des flux automatisés. Comme toujours, Beam Help est un support expert indépendant pour Zoho — nous ne sommes pas le support officiel de Zoho.

Étape par étape

Étape 1. Identifiez les deux identifiants clés dont vous aurez besoin : le ticketId du ticket sur lequel vous travaillez, et le transitionId de la transition de workflow spécifique que vous souhaitez inspecter. Ces deux valeurs sont disponibles à partir d'appels API antérieurs qui listent les tickets et leurs transitions disponibles. ^[1]

Étape 2. Construisez votre requête en utilisant la méthode GET sur le modèle d'endpoint suivant, en remplaçant les espaces réservés par vos valeurs réelles :

GET /api/v1/tickets/{ticketId}/transitions/{transitionId}/duringTransitionForm

Remplacez {ticketId} par l'ID numérique ou textuel du ticket cible, et {transitionId} par l'ID de la transition dont vous souhaitez récupérer le formulaire en cours de processus. ^[1]

Étape 3. Optionnellement, transmettez des paramètres de requête supplémentaires via l'argument p si votre intégration nécessite un filtrage ou une pagination des champs de formulaire retournés. Cela correspond au paramètre p accepté par l'endpoint. ^[1]

Étape 4. Envoyez la requête authentifiée à l'API Zoho Desk. Un exemple minimal en Python utilisant un client préconfiguré ressemble à ceci :

result = client.op_8_get_during_transition_form(
    ticketId="123456",
    transitionId="789",
    p=None  # pass a dict here if you need extra query params
)

La méthode émet une requête GET vers l'URL construite et retourne la définition du formulaire sous forme d'objet de réponse. ^[1]

Étape 5. Analysez la réponse pour extraire les définitions de champs incluses dans le formulaire pendant la transition. Ces champs représentent ce qu'un agent voit et doit remplir avant que la transition ne se termine. Utilisez ces données pour piloter la logique de validation, pré-remplir des valeurs, ou afficher le formulaire dans une interface personnalisée. ^[1]

Erreurs courantes

• Mauvais ID de transition pour l'état actuel du ticket. Toutes les transitions ne sont pas disponibles pour tous les tickets à tout moment. Si vous fournissez un transitionId qui n'est pas actuellement valide pour le statut du ticket, l'API retournera une erreur. Confirmez toujours les transitions disponibles pour un ticket avant d'appeler cet endpoint. ^[1]

• Token OAuth manquant ou expiré. L'API Zoho Desk nécessite un token bearer OAuth 2.0 valide, avec une portée adaptée aux opérations Desk. Un token expiré ou dont la portée est incorrecte entraînera une réponse 401 ou 403, que vos IDs soient corrects ou non. ^[1]

• Confusion entre ticketId et le numéro de ticket. Zoho Desk distingue le numéro de ticket lisible par l'humain (par ex. #1042) et le ticketId interne utilisé par l'API. Utilisez toujours l'ID interne dans le chemin de l'URL. ^[1]

Ce qu'il faut vérifier

• Confirmez que les deux IDs sont corrects — vérifiez que ticketId et transitionId existent et que la transition est actuellement disponible pour l'état de ce ticket avant d'effectuer l'appel. ^[1]
• Inspectez la liste de champs retournée — assurez-vous que les champs du formulaire dans la réponse correspondent à ce que vous attendez que les agents voient dans l'interface Zoho Desk pour cette transition. ^[1]
• Validez la portée de l'authentification — confirmez que votre token OAuth inclut les permissions API Desk nécessaires afin que la requête ne soit pas rejetée avant d'atteindre la logique de transition. ^[1]