Comment récupérer les heures d'ouverture dans Zoho

Récupérer les heures d'ouverture dans Zoho CRM est simple une fois votre connexion OAuth établie — une seule requête GET vers l'endpoint des paramètres renvoie toutes les données d'heures d'ouverture configurées pour votre organisation.

Pourquoi c'est important

Les heures d'ouverture pilotent un ensemble de comportements CRM sensibles au temps, notamment les calculs de SLA, la planification des workflows et les fenêtres de disponibilité du support. Si vous construisez une intégration ou auditez votre configuration Zoho CRM par programmation, vous avez besoin d'un moyen fiable d'extraire ces données sans naviguer dans l'interface à chaque fois. Comprendre l'appel API sous-jacent est également utile pour automatiser les comparaisons d'environnements entre les orgs sandbox et production.

Étape par étape

Étape 1. Assurez-vous de disposer d'une connexion Zoho CRM valide et authentifiée pour l'utilisateur concerné. Le système vérifie si une connexion stockée existe et actualise automatiquement le jeton d'accès s'il expire dans moins de 120 secondes, vous n'avez donc pas besoin de gérer la rotation des jetons manuellement avant d'effectuer l'appel. ^[1]

Étape 2. Obtenez une instance ZohoCrmApi associée à l'utilisateur authentifié. En interne, celle-ci encapsule un ZohoCrmClient qui contient l'apidomain et l'accesstoken courant, ainsi qu'un callback token_refresher capable de renouveler silencieusement les identifiants en cours de session si une erreur 401 est rencontrée. ^[3]

Étape 3. Appelez la méthode de récupération des heures d'ouverture sur l'instance API. L'opération est mappée sur :

GET /settings/business_hours

En Python, elle est invoquée comme suit :

def get_business_hours(self):
    return self.c.request("GET", "/settings/business_hours", version=6)

La requête cible la version 6 de l'API Zoho CRM ; assurez-vous donc que votre client n'est pas codé en dur sur un numéro de version plus ancien. ^[4]

Étape 4. Analysez la réponse. Un appel réussi renvoie un payload JSON contenant la configuration des heures d'ouverture de votre organisation. Si la réponse contient une clé error plutôt que la structure de données attendue, vérifiez la validité du jeton et les permissions de l'org avant de réessayer. ^[4]

Étape 5. Si vous exécutez cette opération dans un environnement de test automatisé, vous pouvez l'invoquer via le mécanisme d'appel d'outil en envoyant une requête POST vers /api/chat avec un corps JSON spécifiant "tool": "getbusinesshours" et un objet params vide. Le serveur extrait le résultat de l'outil depuis data.tool_result dans la réponse. ^[5]

---

Erreurs courantes

• Enregistrement de connexion obsolète ou manquant. Si getzohoconnection renvoie None pour le user_id donné, l'instance API ne peut pas être créée et l'appel échouera silencieusement. Vérifiez toujours que la ligne de connexion existe dans votre base de données avant de continuer. ^[1]

• Mauvaise version de l'API. L'endpoint des heures d'ouverture est explicitement appelé avec version=6. Omettre le paramètre de version ou utiliser une version antérieure par défaut peut renvoyer une erreur 404 ou une structure de réponse inattendue. ^[4]

• Identifiant d'org manquant pour les configurations multi-produits. Si votre intégration utilise également Zoho Desk en parallèle de CRM, sachez que les appels Desk nécessitent un champ orgid distinct (deskorg_id), différent de l'identifiant d'org CRM. Les confondre entraînera des échecs d'authentification sur le mauvais produit. ^[3]

• Expiration du jeton en cours de requête. Bien que la couche de connexion actualise les jetons de manière proactive 120 secondes avant leur expiration, les traitements par lots de longue durée peuvent tout de même rencontrer une erreur 401. Le callback token_refresher est conçu pour gérer ce cas, mais vérifiez qu'il est correctement configuré dans l'instanciation de votre ZohoCrmClient. [^1, ^3]

---

Points à vérifier

• Confirmez la validité du jeton d'accès en vérifiant que tokenexpiresat est dans le futur avant d'effectuer l'appel, ou en vous assurant que la logique d'actualisation automatique s'est exécutée sans erreur. ^[1]
• Vérifiez le domaine API correct (api_domain) stocké dans l'enregistrement de connexion — cette valeur est renvoyée lors de l'échange initial de jeton OAuth et doit correspondre au centre de données sur lequel votre org est hébergée. ^[6]
• Inspectez la réponse brute à la recherche d'une clé error ; si elle est présente, comparez la description de l'erreur avec vos scopes OAuth pour vous assurer que le scope des paramètres CRM est inclus dans Config.ZOHO_SCOPES. [^2, ^6]

---

*Beam Help fournit des conseils d'experts indépendants sur les produits Zoho et ne constitue pas le support officiel de Zoho. Testez toujours les appels API sur une org sandbox avant de les exécuter en production.*