Comment mettre à jour des enregistrements dans Zoho

La mise à jour d'enregistrements dans Zoho nécessite une connexion OAuth valide et active avec les bons périmètres d'autorisation (scopes) — une fois ceux-ci en place, le flux de mise à jour gère automatiquement le renouvellement du token et écrit les modifications dans CRM ou Desk.

Pourquoi c'est important

Que vous synchronisiez des coordonnées de contacts, clôturiez des tickets ou modifiiez des données de prospects, les mises à jour d'enregistrements par programmation dépendent d'un token OAuth actif et des bons périmètres d'autorisation. Si votre token a expiré ou si vos scopes sont trop restrictifs, les appels de mise à jour échoueront silencieusement ou retourneront des erreurs 401. Comprendre le fonctionnement de la couche de connexion vous aide à diagnostiquer et résoudre ces problèmes rapidement.

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

---

Étape par étape

Étape 1. Vérifiez que votre connexion OAuth existe et détient un token valide.

Avant qu'une mise à jour d'enregistrement puisse réussir, le système doit trouver une connexion enregistrée pour votre utilisateur. La connexion est recherchée dans une table locale zohoconnections à l'aide de votre userid. Si aucune ligne n'est trouvée, le client API ne peut pas être initialisé et tous les appels suivants échoueront.^[3]

Étape 2. Laissez le cycle de renouvellement du token s'exécuter.

Les tokens sont renouvelés de manière proactive lorsque l'heure actuelle se situe dans les 120 secondes précédant la valeur tokenexpiresat enregistrée. Un renouvellement réussi écrit le nouvel accesstoken et le tokenexpiresat mis à jour dans la ligne zohoconnections, de sorte que l'appel suivant utilise toujours un identifiant récent.^[3] Si le renouvellement lui-même échoue (par exemple, si le refresh_token est manquant ou révoqué), la fonction retourne None et aucune mise à jour ne sera effectuée.^[1]

Étape 3. Vérifiez que les bons périmètres OAuth sont accordés.

Pour les mises à jour d'enregistrements dans Zoho CRM, votre autorisation OAuth doit inclure ZohoCRM.modules.ALL ou le scope UPDATE équivalent au niveau du module. Pour Zoho Desk, les scopes pertinents incluent Desk.tickets.UPDATE, Desk.contacts.UPDATE, Desk.tasks.UPDATE, ainsi que des permissions UPDATE similaires par objet.^[5] Si ces scopes n'ont pas été demandés lors de l'autorisation OAuth initiale, vous devrez procéder à une nouvelle autorisation en les incluant explicitement.

Étape 4. Initialisez le bon client API pour votre produit.

Passez apptype="crm" pour cibler Zoho CRM, ou apptype="desk" pour cibler Zoho Desk. Pour Desk, un orgid est également requis — s'il n'est pas déjà enregistré, le système appellera getallorganizations pour le découvrir et le persister automatiquement.^[1] Pour CRM, un ZohoCrmClient est construit à l'aide de l'apidomain et de l'access_token enregistrés, avec le callback de renouvellement du token connecté.^[4]

Étape 5. Exécutez l'outil de mise à jour avec l'ID de l'enregistrement cible et les champs modifiés.

Une fois le client API prêt, appelez execute_tool avec le nom de l'outil de mise à jour approprié et un objet params incluant l'id de l'enregistrement ainsi que les champs que vous souhaitez modifier. La couche d'exécution tentera l'appel, et si une question de clarification ou une erreur est retournée dans le résultat, ce message est affiché directement afin que vous puissiez corriger le payload et réessayer.^[8]

Étape 6. Vérifiez que les métadonnées de connexion sont à jour après un callback d'authentification.

Si vous avez récemment procédé à une nouvelle autorisation, vérifiez que le callback d'authentification a correctement écrit le dernier accesstoken, refreshtoken, apidomain et tokenexpiresat dans zohoconnections. Le callback effectue un upsert — mettant à jour la ligne existante si elle est trouvée, ou en insérant une nouvelle dans le cas contraire — et enregistre également crmorgid pour la gestion des tenants CRM.^[2]

---

Pièges courants

• orgid manquant pour les appels Desk. Si deskorg_id est vide ou ne contient que des espaces, le client est tout de même construit, mais le premier appel API déclenche une recherche de découverte automatique. Si cette recherche échoue également (par exemple, en raison d'un manque de scope sur Desk.basic.READ), toutes les mises à jour Desk suivantes retourneront une erreur.^[1]
• Le renouvellement du token ne retourne pas d'accesstoken. Si ZohoOAuth.refreshtokens répond sans clé access_token, le renouvellement retourne None et le token périmé reste utilisé, provoquant des erreurs 401 lors des appels de mise à jour.^[1][3]
• Manque de scopes dans l'autorisation initiale. Les scopes sont définis au moment de l'autorisation. Ajouter des scopes UPDATE à votre fichier de configuration ne met pas rétroactivement à jour une autorisation existante — l'utilisateur doit effectuer un nouveau flux OAuth.^[5]
• Verrouillage SQLite lors de mises à jour simultanées. Les opérations de remplissage ou de migration qui mettent à jour zoho_connections doivent utiliser une seule connexion/transaction pour éviter les conflits de verrouillage.^[6]

---

Ce qu'il faut vérifier

• Confirmez que la ligne zohoconnections correspondant à votre userid possède un refreshtoken non nul et que tokenexpires_at est un timestamp Unix valide.^[3]
• Vérifiez que votre autorisation OAuth inclut le scope UPDATE pertinent pour le module que vous ciblez (par exemple, ZohoCRM.modules.ALL pour CRM, Desk.tickets.UPDATE pour les tickets Desk).^[5]
• Après toute nouvelle autorisation, vérifiez que l'apidomain enregistré dans zohoconnections contient zohoapis. afin que le centre de données soit correctement déduit pour les appels API suivants.^[2]