Comment obtenir les entrées de temps d'un ticket par type de facturation dans Zoho Desk

La récupération des entrées de temps d'un ticket filtrées par type de facturation dans Zoho Desk est simple grâce à un endpoint d'API dédié qui limite les résultats à un seul ticket et les regroupe par classification de facturation.

Pourquoi c'est important

Lorsque votre équipe support enregistre du temps sur des tickets, toutes les heures ne partagent pas le même statut de facturation — certaines peuvent être facturables, d'autres non facturables ou offertes. La possibilité d'extraire les entrées de temps segmentées par type de facturation vous permet de rapprocher les factures, d'auditer l'effort des agents et d'alimenter des workflows de facturation en aval sans avoir à filtrer manuellement une liste complète d'entrées de temps.

Étape par étape

Étape 1. Identifiez le ticketId du ticket dont vous souhaitez récupérer les entrées de temps. Il s'agit de l'identifiant unique que Zoho Desk attribue à chaque ticket de support — vous pouvez le trouver dans l'URL du ticket ou en interrogeant d'abord l'endpoint de liste des tickets. ^[1]

Étape 2. Effectuez une requête GET vers l'endpoint du type de facturation, en substituant l'identifiant de votre ticket dans le chemin :

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

Cette opération (gettickettimeentriesby) retourne les entrées de temps pour le ticket spécifié, organisées par type de facturation. ^[1]

Étape 3. Transmettez les paramètres de requête optionnels via l'argument dictionnaire p. L'endpoint accepte un paramètre p qui peut contenir des options de pagination ou de filtrage en complément du ticketId requis. ^[1]

Étape 4. Si vous effectuez cet appel depuis Python, la méthode wrapper se présente comme suit :

result = client.get_ticket_time_entries_by(
    ticketId="your_ticket_id_here",
    p={"page": 1}   # optional query params
)

La méthode émet une requête GET vers le chemin construit et retourne le payload de réponse contenant les entrées de temps regroupées par type de facturation. ^[1]

Étape 5. Analysez la réponse pour extraire les regroupements par type de facturation. Chaque entrée dans la réponse contiendra le temps enregistré et sa classification de facturation associée, que vous pourrez ensuite utiliser à des fins de facturation ou de reporting. ^[1]

---

Endpoints associés à connaître

Le modèle de filtre par type de facturation est cohérent sur plusieurs entités Zoho Desk, vous pouvez donc appliquer la même approche à différents niveaux de votre modèle de données :

• Entrées de temps par type de facturation au niveau compte : GET /api/v1/accounts/{accountId}/timeEntries/billingType ^[2]
• Entrées de temps par type de facturation au niveau contact : GET /api/v1/contacts/{contactId}/timeEntries/billingType ^[5]
• Entrées de temps par type de facturation au niveau agent : GET /api/v1/agents/{agentId}/timeEntries/billingType ^[6]
• Entrées de temps par type de facturation au niveau tâche : GET /api/v1/tasks/{taskId}/timeEntries/billingType ^[4]

Si vous avez besoin de *toutes* les entrées de temps d'un ticket sans le regroupement par type de facturation, utilisez plutôt l'endpoint associé GET /api/v1/tickets/{ticketId}/timeEntries. ^[8]

Erreurs courantes

• Mauvais endpoint d'entité : Il est facile d'appeler accidentellement la variante compte ou contact alors que vous souhaitez la variante ticket. Vérifiez que votre chemin contient bien tickets/{ticketId} et non accounts/{accountId} ou contacts/{contactId}. ^[1][2][5]
• ticketId manquant ou malformé : Le ticketId est un paramètre de chemin obligatoire. Passer une chaîne vide ou un entier là où une chaîne est attendue entraînera l'échec de la requête ou son routage vers une mauvaise ressource. ^[1]
• Confusion entre cet endpoint et l'endpoint de liste simple : timeEntries/billingType et timeEntries sont des opérations distinctes avec des structures de réponse différentes — utilisez le chemin par type de facturation uniquement lorsque vous avez spécifiquement besoin d'entrées segmentées par classification de facturation. ^[1][8]

Points à vérifier

• Confirmez que le ticketId dans votre chemin de requête correspond à un ticket existant dans votre organisation Zoho Desk avant d'appeler l'endpoint. ^[1]
• Vérifiez que des entrées de temps ont bien été enregistrées sur le ticket, car un ticket valide sans entrées de temps retournera un résultat vide plutôt qu'une erreur. ^[1][8]
• Si vous avez besoin d'une vue plus large (par exemple, tout le temps facturable sur un compte), envisagez de passer à l'endpoint de type de facturation au niveau compte plutôt que de boucler sur des appels de tickets individuels. ^[2]

---

*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Validez toujours le comportement de l'API par rapport à votre plan Zoho Desk spécifique et à la version de l'API.*