Comment obtenir le résumé des entrées de temps d'un ticket dans Zoho Desk

Récupérer un résumé des entrées de temps pour un ticket Zoho Desk vous offre une vue agrégée de tout le temps enregistré sur ce ticket — sans avoir à additionner manuellement chaque entrée. Chez Beam Help (support expert indépendant pour Zoho, et non le support officiel Zoho), nous vous expliquons exactement comment procéder via l'API Zoho Desk.

Pourquoi c'est important

Lorsque vous gérez des opérations de support, vous avez souvent besoin d'un total consolidé rapide du temps passé sur un ticket — pour la facturation, le reporting SLA ou les bilans de productivité des agents. Récupérer chaque entrée individuellement et les additionner manuellement est inefficace à grande échelle. L'endpoint de résumé vous fournit cette agrégation en un seul appel, ce qui fait gagner du temps et réduit le risque d'erreurs de calcul. ^[1]

---

Étape par étape

Étape 1. Vérifiez que votre token OAuth dispose des bons scopes Desk.

Avant d'effectuer tout appel API, confirmez que vos identifiants OAuth incluent au minimum Desk.tickets.READ et Desk.tickets.ALL. Ces scopes régissent l'accès aux données au niveau du ticket, y compris les entrées de temps. Sans eux, l'API retournera une erreur d'autorisation. ^[3]

Étape 2. Identifiez le ticketId que vous souhaitez interroger.

Chaque requête vers l'endpoint de résumé des entrées de temps nécessite un identifiant de ticket valide. Vous pouvez le récupérer depuis l'interface Zoho Desk (il apparaît dans l'URL du ticket) ou de manière programmatique via les endpoints de liste ou de recherche de tickets. Gardez cette valeur à portée de main — vous la substituerez dans le chemin à l'étape suivante. ^[1]

Étape 3. Appelez l'endpoint de résumé des entrées de temps.

Envoyez une requête GET vers :

GET /api/v1/tickets/{ticketId}/timeEntries/summary

Remplacez {ticketId} par l'identifiant de ticket réel obtenu à l'étape 2. En Python, en utilisant le wrapper client Desk, l'appel ressemble à ceci : ^[1]

summary = client.get_summation_of_ticket_time(ticketId="your_ticket_id")

Le paramètre optionnel p peut être transmis sous forme de dictionnaire si vous devez fournir des paramètres de requête supplémentaires pris en charge par la configuration de votre organisation Desk. ^[1]

Étape 4. Analysez la réponse.

La réponse contiendra des données de temps agrégées pour le ticket spécifié. Examinez les champs retournés pour extraire les totaux tels que le temps total enregistré, le temps facturable et le temps non facturable, selon votre cas d'usage. ^[1]

Étape 5. (Optionnel) Croisez avec la ventilation par type de facturation.

Si vous avez besoin du résumé ventilé par classification de facturation, vous pouvez compléter l'appel de résumé par une requête distincte vers l'endpoint de type de facturation :

GET /api/v1/tickets/{ticketId}/timeEntries/billingType

Cet endpoint retourne les entrées de temps regroupées par type de facturation, vous offrant une vue plus granulaire en complément du résumé global. ^[7]

Étape 6. (Optionnel) Explorez les entrées individuelles.

Si un chiffre agrégé nécessite une investigation, vous pouvez récupérer la liste complète des entrées de temps individuelles pour le ticket :

GET /api/v1/tickets/{ticketId}/timeEntries

Ou récupérer une entrée spécifique par son propre identifiant :

GET /api/v1/tickets/{ticketId}/timeEntries/{timeEntryId}

Les deux endpoints acceptent le même dictionnaire de paramètre de requête optionnel p. ^[6][8]

---

Erreurs courantes

• Scopes OAuth manquants ou insuffisants. Si votre token a été généré sans Desk.tickets.READ ou Desk.tickets.ALL, l'endpoint de résumé rejettera la requête. Vérifiez toujours la configuration de vos scopes avant de déboguer la requête elle-même. ^[3]

• ticketId invalide ou incorrect. Passer un identifiant de ticket provenant d'une mauvaise organisation Zoho Desk, ou un identifiant d'enregistrement CRM par erreur, entraînera une erreur de type « non trouvé ». Vérifiez la source de l'identifiant avant d'appeler l'endpoint. ^[1]

• Confusion entre l'endpoint de résumé et l'endpoint de liste. Le chemin /api/v1/tickets/{ticketId}/timeEntries retourne une liste d'entrées individuelles, tandis que /api/v1/tickets/{ticketId}/timeEntries/summary retourne les totaux agrégés. Ce sont des opérations distinctes — assurez-vous d'appeler le bon endpoint selon votre besoin. ^[1][6]

• Tokens d'accès expirés. Les tokens OAuth Zoho expirent généralement après une heure. Si vous recevez une erreur d'authentification sur une intégration qui fonctionnait auparavant, actualisez votre token d'accès avant de réessayer. ^[4]

---

Points à vérifier

• Couverture des scopes : Confirmez que votre token OAuth inclut Desk.tickets.READ ou Desk.tickets.ALL avant d'effectuer l'appel. ^[3]
• Chemin d'endpoint correct : Vérifiez que l'URL contient /timeEntries/summary et non simplement /timeEntries, afin de vous assurer de recevoir des totaux agrégés plutôt qu'une liste brute. ^[1][6]
• Identifiant de ticket valide : Croisez la valeur du ticketId avec votre portail Zoho Desk pour confirmer qu'elle appartient à la bonne organisation et au bon enregistrement de ticket. ^[1]