Comment récupérer les préférences de rendez-vous dans Zoho

La récupération des préférences de rendez-vous dans Zoho CRM est simple grâce à un unique point de terminaison de l'API des paramètres, qui retourne la configuration de planification de votre organisation en un seul appel.

Pourquoi c'est important

Lorsque vous créez des intégrations ou des automatisations autour des fonctionnalités de planification de Zoho CRM, vous avez souvent besoin de lire les préférences de rendez-vous actuelles par programmation — par exemple, pour valider des règles de réservation, synchroniser des fenêtres de disponibilité ou auditer des modifications de configuration. Connaître le point de terminaison exact et savoir comment l'intégrer dans un client authentifié permet d'économiser un temps considérable en essais et erreurs. Comme toujours, Beam Help est un support expert indépendant pour Zoho et ne constitue pas le support officiel de Zoho.

Étape par étape

Étape 1. Assurez-vous que votre connexion OAuth Zoho CRM est active et que votre jeton d'accès est valide. La couche API gère automatiquement le renouvellement du jeton en recherchant le refreshtoken stocké, en appelant le point de terminaison de renouvellement OAuth et en persistant le nouveau accesstoken dans votre base de données avant d'effectuer toute requête en aval. ^[3]

Étape 2. Confirmez que vos portées OAuth incluent les autorisations nécessaires pour les paramètres CRM. Votre configuration de portée doit couvrir ZohoCRM.settings ou la portée plus large ZohoCRM.org.ALL afin que le point de terminaison des paramètres soit accessible. Sans les bonnes portées, la requête sera rejetée avant d'atteindre le serveur. ^[2]

Étape 3. Instanciez votre client API Zoho CRM en utilisant la connexion authentifiée pour l'utilisateur cible. Passez app_type="crm" lors de l'appel de votre fonction de fabrique d'API afin que la bonne classe de client soit initialisée plutôt que la variante Desk. ^[3]

Étape 4. Appelez le point de terminaison des préférences de rendez-vous. Émettez une requête HTTP GET vers /settings/appointment_preferences en utilisant la version 6 de l'API. En Python, cela ressemble à ceci : ^[1]

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

La méthode délègue à votre client HTTP sous-jacent (self.c), qui attache automatiquement le jeton bearer et route vers le domaine du bon centre de données. ^[1]

Étape 5. Analysez la réponse. Le point de terminaison retourne un payload JSON contenant les paramètres de préférences de rendez-vous de votre organisation. Inspectez le dictionnaire retourné pour les champs pertinents à votre cas d'usage — règles de disponibilité, fenêtres de réservation ou paramètres de notification — et gérez les éventuelles clés d'erreur avant de continuer. ^[1]

Points de terminaison de paramètres associés

Si vous avez besoin de récupérer d'autres catégories de préférences en parallèle des données de rendez-vous, deux points de terminaison similaires suivent le même schéma et la même version :

• Préférences d'appel — GET /settings/telephony (opération : getcallpreferences) ^[4]
• Préférences de service — GET /settings/servicepreferences (opération : getservice_preferences) ^[5]

Les trois utilisent la version 6 de l'API et le même client authentifié, vous pouvez donc les regrouper dans une seule session sans vous réauthentifier.

Erreurs courantes

• Jetons d'accès périmés. Si le jeton a expiré et que la logique de renouvellement échoue (par exemple, parce que la ligne refreshtoken est absente de votre base de données), getzoho_api retourne None et l'appel aux paramètres ne sera jamais exécuté. Vérifiez toujours que l'objet API retourné n'est pas None avant d'invoquer une méthode sur celui-ci. ^[3]
• Mauvais apptype. Passer apptype="desk" initialisera un ZohoDeskClient au lieu du client CRM, et le chemin /settings/appointment_preferences n'existera pas sur ce client — entraînant une erreur 404 ou une erreur d'attribut difficile à comprendre. ^[3]
• Portées insuffisantes. Si votre application OAuth a été autorisée avec un ensemble de portées minimal excluant les portées d'organisation ou de paramètres CRM, l'API retournera une erreur d'autorisation. Réautorisez la connexion en incluant la portée complète ZohoCRM.org.ALL. ^[2]

Ce qu'il faut vérifier

• Validité du jeton — confirmez que le accesstoken stocké n'est pas expiré et que la fonction tokenrefresher peut obtenir avec succès un nouveau jeton depuis votre table zoho_connections. ^[3]
• Couverture des portées — vérifiez que ZohoCRM.org.ALL ou une portée de paramètres équivalente est présente dans la liste des portées autorisées pour votre client OAuth. ^[2]
• Version de l'API — assurez-vous que la requête spécifie explicitement la version 6, car le point de terminaison /settings/appointment_preferences est défini pour cette version et peut ne pas se résoudre correctement sur les versions antérieures. ^[1]