Comment lister les entrées de temps d'un ticket dans Zoho Desk

Lister toutes les entrées de temps enregistrées sur un ticket Zoho Desk est simple dès lors que vous connaissez le bon endpoint API et les scopes OAuth requis. Cet article vous guide tout au long du processus — de l'authentification à l'interprétation de la réponse.

Pourquoi c'est important

Les entrées de temps capturent le temps que les agents passent à travailler sur un ticket, et les exposer de manière programmatique vous permet de créer des rapports de facturation, d'auditer l'effort des agents, ou d'alimenter des outils externes de paie et de facturation. Si vous intégrez Zoho Desk avec un système tiers, ou si vous souhaitez simplement extraire des données de suivi du temps en masse, cet endpoint est votre point de départ. Notez que Beam Help est un support expert indépendant pour Zoho — nous ne sommes pas le support officiel de Zoho.

Étape par étape

Étape 1. Vérifiez que vos scopes OAuth incluent les permissions sur les tickets.

Avant d'effectuer tout appel API, vérifiez que votre client OAuth connecté s'est vu accorder les scopes Desk nécessaires. Vous avez au minimum besoin de Desk.tickets.READ dans votre chaîne de scopes ; une configuration plus large inclut également Desk.tickets.ALL aux côtés des scopes pour les contacts, les tâches et les autres modules. ^[2]

Étape 2. Identifiez l'ID du ticket que vous souhaitez interroger.

Chaque requête d'entrée de temps est limitée à un seul ticket. Localisez le ticketId numérique ou alphanumérique du ticket concerné — vous pouvez le trouver dans l'URL de Zoho Desk lors de la consultation du ticket, ou le récupérer de manière programmatique via l'endpoint de liste des tickets. ^[3]

Étape 3. Envoyez une requête GET vers l'endpoint des entrées de temps.

Effectuez un GET HTTP vers le chemin suivant, en remplaçant l'identifiant réel de votre ticket :

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

En Python, en utilisant un wrapper client préconfiguré, l'appel ressemble à ceci :

def list_ticket_time_entries(self, ticketId: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/tickets/{ticketId}/timeEntries", p, None)

Le paramètre optionnel p accepte un dictionnaire de paramètres de chaîne de requête (par exemple, des options de pagination ou de filtrage). ^[3]

Étape 4. (Optionnel) Filtrez les résultats par type de facturation.

Si vous n'avez besoin que des entrées regroupées ou filtrées par leur classification de facturation, utilisez plutôt la sous-ressource dédiée au type de facturation :

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

Cela renvoie les entrées de temps organisées par catégorie de facturation plutôt qu'une liste plate. ^[6]

Étape 5. (Optionnel) Récupérez un résumé agrégé plutôt que des entrées individuelles.

Lorsque vous avez besoin de totaux agrégés — comme le total des heures facturables pour un ticket — appelez l'endpoint de résumé :

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

Cela vous donne une somme de tout le temps enregistré sur le ticket sans retourner chaque enregistrement individuel. ^[7]

Étape 6. Gérez la pagination avec le paramètre p.

L'endpoint de liste principal et l'endpoint de type de facturation acceptent tous deux un dictionnaire p pour les paramètres de requête. Passez les clés de pagination (telles que from et limit) dans ce dictionnaire pour parcourir les grands ensembles de résultats. ^[3][6]

Étape 7. Créez ou mettez à jour des entrées si nécessaire.

Une fois que vous pouvez lire les entrées, vous souhaiterez peut-être également les écrire. Pour enregistrer une nouvelle entrée, envoyez un POST vers le même chemin de base avec un payload data :

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

Pour modifier une entrée existante, utilisez une requête PATCH qui inclut également le timeEntryId :

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

^[8][4]

Erreurs courantes

• Scopes manquants ou insuffisants. Si votre token a été généré sans Desk.tickets.READ (ou Desk.tickets.ALL), l'API retournera une erreur d'autorisation. Régénérez votre token OAuth avec la chaîne de scopes correcte avant de réessayer. ^[2]
• Format d'ID de ticket incorrect. Passer un *numéro* de ticket (la référence lisible par l'humain affichée dans l'interface) au lieu de l'*ID* interne du ticket entraînera une réponse 404 ou vide. Utilisez toujours l'identifiant interne. ^[3]
• Confusion entre l'endpoint de liste et l'endpoint de résumé. Le chemin /timeEntries retourne des enregistrements individuels ; /timeEntries/summary retourne des totaux agrégés. Appeler le mauvais vous donnera des données dans une forme inattendue. ^[3][7]

Ce qu'il faut vérifier

• Confirmez que votre token d'accès OAuth inclut Desk.tickets.READ ou Desk.tickets.ALL dans ses scopes accordés avant d'effectuer la requête. ^[2]
• Vérifiez que le ticketId dans votre chemin de requête est bien l'ID d'enregistrement interne de Zoho Desk, et non le numéro de ticket affiché. ^[3]
• Si vous attendez plusieurs pages de résultats, assurez-vous de passer les paramètres de pagination appropriés dans le dictionnaire p afin qu'aucune entrée ne soit omise silencieusement. ^[3][6]