Comment récupérer les heures de shift dans Zoho

Récupérer les heures de shift dans Zoho CRM est simple une fois votre connexion OAuth établie — un seul appel API vers l'endpoint des paramètres renvoie l'intégralité de la configuration des heures de shift pour votre organisation.

Pourquoi c'est important

Les heures ouvrables et les calendriers de shift pilotent les calculs de SLA, les déclencheurs d'automatisation et les fenêtres de disponibilité du support dans Zoho CRM. Si vous construisez une intégration ou auditez votre configuration CRM de manière programmatique, vous avez besoin d'un moyen fiable pour extraire ces données sans naviguer manuellement dans l'interface. Comprendre l'appel API sous-jacent est également utile pour diagnostiquer les écarts entre le comportement attendu et le comportement réel des heures ouvrables.

Étape par étape

Étape 1. Vérifiez qu'une connexion OAuth valide existe pour l'utilisateur.

Avant qu'un appel API puisse aboutir, votre application doit disposer d'un jeton d'accès actif pour le compte Zoho cible. L'enregistrement de connexion est recherché par user_id dans votre store local, et si le jeton expire dans moins de 120 secondes, il est automatiquement renouvelé avant l'envoi de la requête — cette marge de renouvellement anticipé réduit les erreurs 401 en cours de requête. ^[1]

Étape 2. Instanciez le client API Zoho CRM.

Utilisez le helper getzohoapi en lui passant le userid concerné et en spécifiant "crm" comme apptype. Cette fonction récupère la connexion stockée, configure un callback token_refresher pour une ré-authentification transparente, et retourne une instance ZohoCrmApi prête à l'emploi ainsi que l'enregistrement de connexion. ^[4]

Étape 3. Appelez l'outil getshifthours.

Une fois le client API en main, invoquez getshifthours. En coulisses, cela émet une requête HTTP GET vers l'endpoint /settings/shift_hours en utilisant la version 6 de l'API. ^[2]

result = api.get_shift_hours()

La méthode est également exposée en tant qu'outil nommé (getshifthours) dans le registre d'outils CRM, ce qui permet de la déclencher via le chemin de dispatch standard execute_tool. ^[5]

Étape 4. Traitez la réponse.

L'appel retourne l'objet de configuration des heures de shift depuis Zoho CRM. Analysez le dictionnaire retourné pour en extraire les détails de planning dont vous avez besoin. Si la réponse contient une clé "error", vérifiez d'abord la validité du jeton — la couche OAuth retourne {"error": "No access token in response"} lorsque l'échange ou le renouvellement du jeton échoue. ^[3]

Étape 5. Renouvelez les jetons de manière proactive dans un contexte de test ou de traitement par lot.

Lorsque vous exécutez plusieurs appels API séquentiels (par exemple lors de tests d'intégration), vérifiez à nouveau la valeur tokenexpiresat avant chaque appel et invoquez le token_refresher si l'heure actuelle se situe dans la fenêtre de tolérance de 120 secondes. Ce schéma empêche l'expiration d'une session valide en cours de traitement. ^[6]

---

Pièges courants

• Enregistrement de connexion obsolète ou manquant. Si getzohoconnection retourne None, aucun appel API ne peut être effectué. Vérifiez que la table zohoconnections contient bien une ligne pour le userid cible avant de continuer. ^[1]

• Mauvais apptype passé à getzohoapi. Passer "desk" au lieu de "crm" acheminera la requête via le client Zoho Desk, qui n'expose pas l'endpoint /settings/shifthours. Utilisez toujours "crm" pour cette opération. ^[4]

• Incompatibilité de version d'API. L'implémentation de getshifthours cible explicitement la version 6 de l'API Zoho CRM. Remplacer la version dans un wrapper client personnalisé peut entraîner une erreur 404 ou un schéma de réponse inattendu. ^[2]

• Lacunes dans les scopes OAuth. Le jeton d'accès doit avoir été accordé avec le scope approprié de lecture des paramètres CRM lors du flux d'autorisation initial. Si le jeton a été émis sans les permissions de lecture des paramètres, l'endpoint retournera une erreur d'autorisation même si le jeton lui-même est valide. ^[7]

---

Ce qu'il faut vérifier

• Fraîcheur du jeton : Confirmez que tokenexpiresat dans votre enregistrement de connexion est dans le futur (en tenant compte de la tolérance de 120 secondes) avant d'effectuer l'appel. ^[1]
• Endpoint et version corrects : Vérifiez que votre client cible bien GET /settings/shift_hours à la version 6 de l'API. ^[2]
• Structure de la réponse : Assurez-vous que l'objet retourné ne contient pas de clé "error" ; si c'est le cas, réexaminez vos scopes OAuth et la validité de votre jeton de rafraîchissement. ^[3]

---

*Beam Help est une ressource d'assistance experte indépendante pour les utilisateurs de Zoho — nous ne sommes pas le support officiel de Zoho. Pour les problèmes au niveau de la plateforme, référez-vous toujours à la documentation officielle de Zoho.*