Comment créer des enregistrements dans Zoho

Créer des enregistrements dans Zoho CRM ou Zoho Desk est simple dès lors que votre connexion OAuth et les permissions de module sont correctement configurées — voici ce que vous devez savoir pour bien procéder.

> Beam Help est un support expert indépendant pour Zoho — et non le support officiel de Zoho.

Pourquoi c'est important

Que vous ajoutiez de nouveaux Leads, Contacts, Tickets ou Tâches, chaque appel de création d'enregistrement dépend de la présence des scopes OAuth appropriés et d'une connexion valide. Une mauvaise configuration entraîne des échecs silencieux ou des erreurs de permission difficiles à diagnostiquer. Comprendre le flux complet — des scopes à l'appel API jusqu'au lien vers l'enregistrement créé — permet d'économiser un temps considérable en débogage.

Étape par étape

Étape 1. Vérifiez que vos scopes OAuth incluent les permissions CREATE.

Avant qu'un enregistrement puisse être écrit, votre token OAuth Zoho doit porter le scope approprié. Pour les enregistrements Zoho CRM, vous avez besoin de scopes tels que ZohoCRM.modules.ALL ou un scope CREATE spécifique au module. Pour Zoho Desk, les scopes concernés incluent notamment Desk.tickets.CREATE, Desk.contacts.CREATE, Desk.tasks.CREATE et Desk.events.CREATE. ^[2]

Étape 2. Assurez-vous que votre connexion Zoho est active et authentifiée.

Votre application doit disposer d'un accesstoken et d'un refreshtoken valides, stockés pour votre compte utilisateur. Ceux-ci sont capturés lors du callback OAuth et sauvegardés avec votre apidomain, votre dc (centre de données) et votre crmorg_id. Si la connexion est absente ou expirée, toute tentative de création d'enregistrement retournera une erreur du type *« Zoho is not connected for this app. Please reconnect. »* ^[3][5]

Étape 3. Identifiez le module correct pour votre enregistrement.

Chaque enregistrement appartient à un module — par exemple Leads, Contacts, Deals ou Accounts dans Zoho CRM, ou tickets dans Zoho Desk. Le nom du module est un paramètre obligatoire transmis avec les données de l'enregistrement. Assurez-vous que le nom du module correspond exactement à ce qu'attend l'API, car toute discordance entraînera l'échec de la requête. ^[1]

Étape 4. Soumettez la requête de création via l'outil ou l'appel API approprié.

Passez le nom de l'outil choisi et un objet params incluant le module ainsi que toutes les valeurs de champs obligatoires. Le système exécutera l'outil et, si l'opération est classifiée comme une action d'écriture, elle pourra d'abord être mise en attente en tant qu'action « planifiée » avec un risk_level attribué avant que l'exécution ne soit approuvée. ^[4]

Étape 5. Approuvez l'action planifiée si nécessaire.

Les opérations d'écriture — y compris la création d'enregistrements — sont souvent maintenues dans un statut planned stocké dans adminactions avant d'être appliquées. Une fois le plan confirmé, le système appelle applyplan, qui exécute l'outil avec vos paramètres et tente de créer l'enregistrement dans Zoho. ^[6]

Étape 6. Récupérez le lien direct vers votre nouvel enregistrement.

Après une création réussie, le système génère une URL directe vers le nouvel enregistrement. Pour Zoho CRM, le lien suit le modèle https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. Pour les tickets Zoho Desk, le modèle est https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}. Ces liens sont retournés avec la réponse API afin que vous puissiez accéder directement au nouvel enregistrement. ^[1][6]

Erreurs courantes

• Scopes manquants ou insuffisants. Si votre token OAuth a été généré sans les scopes CREATE pour le module concerné, l'API rejettera la requête. Vous devez réautoriser et vous assurer que tous les scopes requis — tels que Desk.tickets.CREATE ou l'équivalent CRM — sont inclus. ^[2]

• Connexion expirée ou absente. Si aucune connexion valide n'existe pour votre compte utilisateur, le système ne peut pas récupérer un access_token et s'arrêtera avant tout appel API. Une nouvelle authentification via le flux OAuth résoudra ce problème. ^[3][5]

• Mauvais paramètre de centre de données (dc). Votre connexion stocke une valeur dc (par ex. com, eu, in) dérivée de l'api_domain retourné lors de l'OAuth. Si cette valeur est incorrecte, les URLs d'enregistrements générées et les endpoints API pointeront vers la mauvaise région, provoquant des échecs. ^[1][5]

• Opérations d'écriture bloquées en mode lecture seule. Certains contextes de chat ou d'automatisation sont initialisés avec read_only=True, ce qui signifie que les outils de création/écriture ne seront ni proposés ni exécutés. Assurez-vous d'opérer dans un contexte qui autorise les actions d'écriture. ^[3]

Ce qu'il faut vérifier

• Vérifiez que vos scopes OAuth incluent la permission CREATE appropriée pour votre module cible (CRM ou Desk) avant de tenter la création d'un enregistrement. ^[2]
• Confirmez que votre enregistrement de connexion contient un accesstoken non expiré ainsi que les valeurs correctes pour dc et crmorg_id. ^[5]
• Vérifiez l'URL de l'enregistrement retournée après la création pour confirmer que l'enregistrement a bien été écrit dans le module et le centre de données attendus. ^[1][6]