Comment obtenir le récapitulatif des entrées de temps d'une tâche dans Zoho Desk

Récupérer un récapitulatif des entrées de temps pour une tâche spécifique dans Zoho Desk est simple grâce à un seul appel API qui renvoie les données de temps agrégées pour cette tâche. Voici tout ce dont vous avez besoin pour que cela fonctionne correctement.

Pourquoi c'est important

Lors de la gestion des opérations de support, les responsables d'équipe ont souvent besoin d'une vue consolidée du temps que les agents ont enregistré pour une tâche particulière — sans avoir à parcourir chaque entrée individuelle. L'endpoint de récapitulatif vous fournit ce total agrégé en une seule requête, ce qui le rend idéal pour les tableaux de bord de reporting, les révisions de facturation ou les audits SLA. Si vous construisez des automatisations ou des intégrations sur Zoho Desk, c'est l'appel à utiliser chaque fois qu'un total de temps par tâche est requis.

Étape par étape

Étape 1. Vérifiez que votre token OAuth inclut le scope Zoho Desk approprié pour les tâches. Le token doit comporter au minimum Desk.tasks.READ (ou le scope plus large Desk.tasks.ALL) avant que l'API n'autorise la requête. Sans ce scope, l'appel retournera une erreur de permissions. ^[7]

Étape 2. Identifiez le taskId de la tâche que vous souhaitez récapituler. Il s'agit de l'identifiant unique que Zoho Desk attribue à chaque enregistrement de tâche. Vous pouvez le récupérer à partir d'un appel API de liste de tâches précédent ou directement depuis l'URL de la tâche dans le portail Desk. ^[1]

Étape 3. Effectuez une requête GET vers l'endpoint suivant, en remplaçant l'identifiant par celui de votre tâche :

GET /api/v1/tasks/{taskId}/timeEntries/summary

L'opération de l'endpoint est getsummationoftasktime et elle accepte deux paramètres : taskId (obligatoire, chaîne de caractères) et un paramètre optionnel p pour des options de requête supplémentaires. ^[1]

Étape 4. En Python, l'appel ressemble à ceci :

def get_summation_of_task_time(self, taskId: str, p: dict = None):
    """Get Summation of Task Time Entries"""
    return self.c.request("GET", f"/api/v1/tasks/{taskId}/timeEntries/summary", p, None)

Passez l'identifiant de la tâche en tant que taskId. Si vous avez besoin de filtrer ou de paginer les données sous-jacentes, fournissez un dictionnaire de paramètres de requête via p ; sinon, laissez-le à None. ^[1]

Étape 5. Analysez la réponse. L'API renvoie un objet récapitulatif contenant les chiffres de temps agrégés pour toutes les entrées enregistrées pour cette tâche. Présentez les champs clés — tels que le temps total enregistré — à vos utilisateurs dans un format lisible plutôt que d'exposer des identifiants internes bruts. ^[8]

Erreurs courantes

• Scope manquant ou incorrect. La cause la plus fréquente d'une réponse 401 ou 403 est un token OAuth généré sans Desk.tasks.READ ou Desk.tasks.ALL. Réautorisez la connexion en incluant les scopes corrects. ^[7]
• taskId incorrect. Passer un identifiant de ticket ou de contact à la place d'un identifiant de tâche entraînera une réponse 404 ou une réponse vide. Vérifiez toujours que l'identifiant provient d'un enregistrement de tâche, et non d'une autre entité Zoho Desk. ^[1]
• Omettre entièrement le paramètre p plutôt que de passer None. Le paramètre est optionnel, donc passer None est sans risque, mais si votre framework d'intégration requiert un dictionnaire vide explicite, utilisez {} à la place pour éviter des erreurs d'argument inattendues. ^[1]

Ce qu'il faut vérifier

• Vérifiez que le token OAuth utilisé inclut Desk.tasks.READ ou Desk.tasks.ALL dans ses scopes accordés avant d'effectuer l'appel. ^[7]
• Confirmez que la valeur taskId correspond à une tâche valide dans votre portail Zoho Desk, et non à un ticket ou à un autre type d'enregistrement. ^[1]
• Inspectez les champs de la réponse récapitulative et assurez-vous que votre code en aval gère les cas où aucune entrée de temps n'a encore été enregistrée (le récapitulatif peut renvoyer des valeurs nulles plutôt qu'un corps vide). ^[1]

---

*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho.*