Comment récupérer les entrées de temps d'un ticket dans Zoho Desk

Zoho Desk expose plusieurs endpoints API dédiés à la lecture des entrées de temps sur un ticket — de la liste de toutes les entrées à la récupération d'un enregistrement unique ou d'un récapitulatif agrégé. Voici comment utiliser chacun d'eux efficacement.

Pourquoi c'est important

Le suivi du temps dans Zoho Desk est essentiel pour la facturation, le reporting SLA et l'analyse de la productivité des agents. Que vous ayez besoin d'extraire toutes les heures enregistrées sur un ticket de support, de filtrer par type de facturation ou d'afficher un récapitulatif du temps total dans un tableau de bord, l'API REST de Desk fournit des endpoints conçus à cet effet pour chaque scénario. En tant qu'expert indépendant (et non support officiel de Zoho), Beam Help vous guide à travers chaque option ci-dessous.

Étape par étape

Étape 1. Vérifiez vos scopes OAuth.

Avant d'effectuer toute requête liée aux entrées de temps, vérifiez que votre token OAuth inclut au minimum Desk.tickets.READ et Desk.tickets.ALL dans sa liste de scopes. Ces scopes régissent l'accès en lecture aux sous-ressources des tickets, y compris les entrées de temps. ^[7]

Étape 2. Listez toutes les entrées de temps d'un ticket.

Pour récupérer toutes les entrées de temps enregistrées sur un ticket spécifique, envoyez une requête GET vers :

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

Remplacez {ticketId} par l'identifiant numérique du ticket que vous interrogez. Un dictionnaire de paramètres p optionnel peut être transmis pour contrôler la pagination ou le filtrage. ^[4]

Exemple (Python) :

entries = desk_client.list_ticket_time_entries(ticketId="123456")

Étape 3. Récupérez une entrée de temps unique par son identifiant.

Lorsque vous connaissez déjà le timeEntryId spécifique que vous souhaitez consulter, appelez l'endpoint de l'enregistrement individuel :

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

ticketId et timeEntryId sont tous deux des paramètres de chemin obligatoires. Un dictionnaire p optionnel peut transporter des paramètres de requête supplémentaires. ^[3]

Exemple (Python) :

entry = desk_client.get_ticket_time_entry(ticketId="123456", timeEntryId="789")

Étape 4. Obtenez un récapitulatif (total) de tout le temps enregistré.

Si vous n'avez besoin que des totaux agrégés plutôt que des enregistrements individuels — utile pour les tableaux de bord ou les récapitulatifs de facturation — utilisez l'endpoint de récapitulatif :

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

Cet endpoint renvoie une vue agrégée du temps enregistré pour le ticket plutôt qu'une liste d'entrées individuelles. ^[5]

Exemple (Python) :

summary = desk_client.get_summation_of_ticket_time(ticketId="123456")

Étape 5. Filtrez les entrées de temps par type de facturation.

Pour segmenter les entrées de temps selon qu'elles sont facturables ou non facturables, utilisez le sous-endpoint de type de facturation :

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

Transmettez les critères de filtrage pertinents via le dictionnaire de paramètres p. ^[2]

Exemple (Python) :

billable = desk_client.get_ticket_time_entries_by(ticketId="123456", p={"billingType": "Billable"})

Étape 6. Mettez à jour une entrée de temps si des corrections sont nécessaires.

Si une entrée récupérée contient des données incorrectes, vous pouvez la modifier avec une requête PATCH vers :

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

Fournissez les champs à modifier dans le dictionnaire data. ^[6]

Exemple (Python) :

desk_client.update_ticket_time_entry(
    ticketId="123456",
    timeEntryId="789",
    data={"timeSpent": "02:30"}
)

Erreurs courantes

• Scopes manquants. Les requêtes renverront une erreur 401 ou 403 si Desk.tickets.READ ou Desk.tickets.ALL est absent du token. Vérifiez toujours la liste des scopes lors de la configuration OAuth. ^[7]
• Confusion entre les endpoints de récapitulatif et de liste. Le chemin /summary renvoie des totaux agrégés, et non des lignes individuelles. Tenter d'itérer dessus comme une liste provoquera des erreurs inattendues. ^[5]
• Ordre de chemin incorrect. Les sous-chemins /billingType et /summary doivent apparaître après /timeEntries dans l'URL. Inverser ou omettre un segment entraînera une erreur 404. ^[2][5]

Points à vérifier

• Confirmez que le ticketId que vous utilisez est valide et appartient au portail Zoho Desk de votre organisation avant d'appeler un endpoint. ^[4]
• Vérifiez que votre token OAuth n'a pas expiré et qu'il contient les scopes Desk.tickets appropriés. ^[7]
• Après une mise à jour via PATCH, récupérez à nouveau l'entrée avec gettickettime_entry pour confirmer que les modifications ont été appliquées comme prévu. ^[3][6]