L'API REST de Zoho Desk expose trois endpoints dédiés qui vous permettent de récupérer les données d'entrées de temps pour n'importe quel agent — sous forme de liste complète, d'enregistrement unique ou filtrées par type de facturation.
Pourquoi c'est important
Lorsque vous devez auditer la façon dont les agents utilisent leur temps, générer des rapports de facturation ou alimenter des données de suivi du temps dans un système externe, vous devez pouvoir interroger les entrées de temps des agents par programmation. Zoho Desk fournit des opérations API spécialement conçues pour ce cas d'usage, et savoir quel endpoint appeler — et avec quels paramètres — permet d'économiser un effort de développement considérable.
> Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho.
---
Étape par étape
Étape 1. Identifiez l'agent dont vous avez besoin des entrées de temps.
Chaque requête nécessite un agentId. Il s'agit de l'identifiant unique de l'enregistrement de l'agent au sein de votre organisation Zoho Desk. Vous pouvez l'obtenir depuis la section Agents de votre panneau d'administration Desk ou à partir d'un appel API préalable qui retourne des objets agent. Gardez cette valeur à portée de main — elle apparaît dans le chemin URL pour les trois opérations ci-dessous. [5]
Étape 2. Listez toutes les entrées de temps d'un agent.
Envoyez une requête GET vers le chemin suivant, en substituant l'identifiant de l'agent :
GET /api/v1/agents/{agentId}/timeEntriesL'opération est nommée listagenttime_entries. Un objet paramètre p optionnel vous permet de transmettre des filtres en chaîne de requête (tels que la pagination ou la plage de dates) avec la requête. En Python, l'appel ressemble à ceci :
client.list_agent_time_entries(agentId="12345678", p={"from": 1, "limit": 50})Cela retourne la collection complète des entrées de temps enregistrées pour cet agent. [5]
Étape 3. Récupérez une entrée de temps unique et spécifique.
Si vous connaissez déjà l'identifiant d'une entrée de temps particulière — par exemple, depuis la liste retournée à l'étape 2 — vous pouvez récupérer uniquement cet enregistrement avec :
GET /api/v1/agents/{agentId}/timeEntries/{timeEntryId}L'opération est nommée getagenttime_entry et nécessite à la fois agentId et timeEntryId comme paramètres de chemin. Le dictionnaire p optionnel peut contenir tout paramètre de requête supplémentaire dont votre intégration a besoin. [7]
client.get_agent_time_entry(agentId="12345678", timeEntryId="98765432")Étape 4. Filtrez les entrées de temps par type de facturation.
Lorsque vous souhaitez uniquement les entrées correspondant à une classification de facturation spécifique (par exemple, facturable ou non facturable), utilisez la variante de l'endpoint par type de facturation :
GET /api/v1/agents/{agentId}/timeEntries/billingTypeL'opération est nommée getagenttimeentriesby. Transmettez le type de facturation souhaité via le dictionnaire de paramètres p. Cela est particulièrement utile lors de la génération de factures ou du rapprochement des heures facturables. [3]
client.get_agent_time_entries_by(agentId="12345678", p={"type": "Billable"})Étape 5. Traitez la réponse.
Les trois endpoints retournent du JSON. Analysez le corps de la réponse pour extraire les champs d'entrée de temps dont vous avez besoin — tels que la durée, la référence du ticket et la classification de facturation — et intégrez-les dans votre flux de travail de reporting ou de facturation. [5][7][3]
---
Erreurs courantes
- Format d'
agentIdincorrect. Transmettre un nom d'affichage ou une adresse e-mail au lieu de l'identifiant numérique de l'agent entraînera une réponse 404 ou vide. Résolvez toujours l'identifiant de l'agent via l'API avant de construire votre requête. [5] - Confusion entre l'endpoint par type de facturation et l'endpoint de liste. Le chemin
/timeEntries/billingTypeest une route distincte, et non une sous-ressource d'une entrée spécifique. N'insérez pas detimeEntryIdentretimeEntriesetbillingType. [3] - Paramètres de pagination manquants. L'endpoint de liste (
/timeEntries) peut retourner un ensemble de résultats paginés. Si vous omettez les contrôles de pagination dans le dictionnairep, vous ne recevrez peut-être que la première page d'entrées et manquerez silencieusement les enregistrements plus anciens. [5]
---
Points à vérifier
- Confirmez que l'
agentIdque vous utilisez correspond à un agent actif dans votre organisation Zoho Desk avant d'effectuer des requêtes en masse. - Vérifiez que vos identifiants API disposent de la portée de permission de lecture Time Entry ; sans elle, les trois endpoints retourneront une erreur d'autorisation.
- Après avoir récupéré les entrées, recoupez au moins un enregistrement avec l'interface de Zoho Desk (profil de l'agent → entrées de temps) pour confirmer que les données correspondent à ce qui est affiché dans le portail. [5][7][3]