Comment récupérer la timeline dans Zoho

La récupération d'une timeline dans Zoho nécessite un jeton d'accès OAuth valide et une connexion correctement configurée à l'API Zoho — une fois ces éléments en place, votre intégration peut appeler les outils appropriés pour extraire les données de timeline de n'importe quel module pris en charge.

Pourquoi c'est important

Les données de timeline vous offrent une vue chronologique de l'activité associée à un enregistrement — utile pour auditer les modifications, consulter l'historique des communications ou générer des rapports. Si votre jeton d'accès a expiré ou si votre connexion est mal configurée, toute tentative de récupération des informations de timeline échouera silencieusement ou renverra une erreur 401. Comprendre le fonctionnement de la couche d'authentification est donc un prérequis avant tout appel de récupération de données.

> Remarque : Beam Help est un support expert indépendant pour Zoho — nous ne sommes pas le support officiel de Zoho.

---

Étape par étape

Étape 1. Établissez votre connexion OAuth.

Avant toute chose, votre application doit compléter le flux OAuth. L'URL d'autorisation est construite à partir de votre clientid, de votre redirecturi, des scopes configurés, ainsi que des paramètres responsetype=code, accesstype=offline et prompt=consent. Une fois que l'utilisateur a approuvé, Zoho redirige vers votre application avec un code d'autorisation. ^[7]

Étape 2. Échangez le code d'autorisation contre des jetons.

Envoyez le code d'autorisation en POST à l'endpoint de jeton de Zoho en utilisant granttype=authorizationcode avec votre clientid, votre clientsecret et votre redirecturi. Une réponse réussie retourne un accesstoken, un refreshtoken, un apidomain et une valeur expires_in. Conservez tous ces éléments — vous en aurez besoin pour chaque requête ultérieure. ^[7]

Étape 3. Persistez la connexion et suivez l'expiration.

Sauvegardez l'accesstoken, le refreshtoken, le tokenexpiresat (calculé comme le temps Unix actuel plus expiresin) et l'apidomain dans votre stockage de données. L'horodatage d'expiration est essentiel : il indique à votre système quand le jeton doit être actualisé avant d'effectuer des appels API. ^[1]

Étape 4. Actualisez le jeton avant son expiration.

Lors de la récupération de la connexion stockée, vérifiez si le temps actuel se situe dans les 120 secondes précédant tokenexpiresat. Si c'est le cas, envoyez un POST à l'endpoint de jeton avec granttype=refreshtoken, votre clientid, votre clientsecret et le refreshtoken stocké. En cas de succès, mettez à jour l'accesstoken stocké et le tokenexpiresat avec les nouvelles valeurs. Ce tampon de 120 secondes réduit le risque d'expiration du jeton en cours de requête. ^{[2] [3]}

Étape 5. Confirmez que la connexion est active avant d'appeler un outil.

Une fois la logique d'actualisation exécutée, vérifiez qu'un objet de connexion valide existe pour l'utilisateur. Si aucune connexion n'est trouvée — par exemple parce que l'utilisateur n'a jamais autorisé l'accès ou que l'actualisation a échoué — affichez une invite de reconnexion plutôt que de continuer. Tenter d'appeler des outils Zoho sans jeton actif entraînera une réponse d'erreur. ^[6]

Étape 6. Identifiez l'outil et le module appropriés pour la récupération de la timeline.

Une fois la connexion valide établie, déterminez quel outil Zoho correspond aux données de timeline pour votre module cible (par exemple, Contacts, Leads ou Deals dans Zoho CRM). L'api_domain retourné lors de l'échange de jetons constitue l'URL de base pour tous les appels API — utilisez-le lors de la construction de votre ZohoCrmClient. Transmettez le nom de l'outil et les paramètres requis (tels que module) à la couche d'exécution. ^[4]

Étape 7. Exécutez l'appel d'outil.

Invoquez l'outil via votre couche d'exécution API en fournissant le nom de l'outil et un dictionnaire de paramètres. Le système appellera l'API de Zoho en utilisant le jeton d'accès actuel et retournera la charge utile de la timeline. Si le jeton a été renouvelé en cours de session, le callback d'actualisation du jeton en obtiendra automatiquement un nouveau et réessaiera. ^{[4] [5]}

Étape 8. Traitez la réponse.

Un appel réussi retourne les enregistrements de la timeline sous forme de données structurées. Si la réponse contient une clé error, examinez le message — les causes courantes incluent un jeton expiré qui n'a pas pu être actualisé, un nom de module invalide ou des scopes OAuth insuffisants. ^{[3] [4]}

---

Erreurs courantes

• refreshtoken manquant lors des échanges ultérieurs. Zoho ne retourne un refreshtoken que lors de la toute première autorisation. Si vous le perdez, l'utilisateur doit réautoriser depuis le début. Persistez-le immédiatement après l'échange de code initial. ^[7]
• Expiration du jeton mal suivie. tokenexpiresat doit être défini comme int(time.time()) + int(expires_in) au moment où le jeton est reçu — et non au moment où il est stocké. Tout délai entre la réception et le stockage entraînera des calculs d'expiration prématurés. ^{[1] [3]}
• Mauvais apidomain utilisé. L'apidomain dans la réponse de jeton peut varier selon le centre de données (par ex., .com, .eu, .in). Utilisez toujours le domaine retourné lors de l'échange de jetons plutôt que de coder une URL en dur. ^[7]
• Incohérence du champ d'identifiant d'organisation. Lors de la récupération des informations utilisateur depuis https://accounts.zoho.<DC>/oauth/user/info, l'identifiant d'organisation peut apparaître sous orgid, organizationid ou ZGID selon le centre de données. Implémentez une logique de repli pour gérer toutes les variantes. ^[1]

---

Ce qu'il faut vérifier

• Le jeton est valide et ne se trouve pas dans les 120 secondes précédant son expiration avant d'émettre tout appel de récupération de timeline — confirmez que la logique d'actualisation s'est exécutée avec succès et que le nouvel access_token a été persisté. ^[2]
• L'api_domain correspond au centre de données de l'utilisateur — vérifiez que le domaine stocké lors de l'échange de jetons est utilisé comme URL de base pour toutes les requêtes API Zoho. ^{[4] [7]}
• Les scopes OAuth requis sont inclus — assurez-vous que les scopes configurés dans votre URL d'autorisation couvrent l'accès en lecture au module dont vous interrogez la timeline. ^[7]