Comment récupérer un enregistrement unique dans Zoho

Récupérer un enregistrement unique dans Zoho CRM via l'API consiste à cibler une entrée spécifique par son identifiant unique, en renvoyant uniquement les données dont vous avez besoin sans extraire une liste entière.

Pourquoi c'est important

Lors de la création d'intégrations ou d'automatisations, récupérer une liste complète d'enregistrements juste pour en lire un seul est inefficace et lent. Cibler un enregistrement par son identifiant permet de limiter les appels API, d'éviter d'atteindre les limites de débit, et de rendre vos workflows Deluge ou REST bien plus faciles à maintenir. Ce modèle est particulièrement courant lorsqu'un déclencheur (tel qu'un workflow ou un webhook) vous fournit déjà un identifiant d'enregistrement et que vous avez simplement besoin d'enrichir ou de valider les données de cet enregistrement.

> 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. Obtenez un jeton d'accès OAuth valide pour Zoho CRM.

Avant tout appel API, votre client doit échanger ses identifiants contre un jeton bearer. Ce jeton est transmis dans chaque en-tête de requête sous la forme Authorization: Zoho-oauthtoken <your_token>. Sans cela, l'API CRM rejettera la requête. ^[3]

Étape 2. Identifiez le module et l'identifiant de l'enregistrement que vous souhaitez récupérer.

Zoho CRM organise les données en modules tels que Leads, Contacts, Accounts, Deals, etc. Chaque enregistrement au sein d'un module possède un id numérique unique (par exemple, 3652397000009851001). Vous devez connaître à la fois le nom du module et l'identifiant de l'enregistrement avant d'effectuer l'appel. ^[3]

Étape 3. Construisez la requête GET vers le point de terminaison d'enregistrement unique.

L'API Zoho CRM v8 expose les enregistrements individuels à l'adresse suivante :

GET https://www.zohoapis.com/crm/v8/{Module}/{record_id}

Remplacez {Module} par le nom API du module (par ex., Leads, Contacts) et {record_id} par l'identifiant numérique de l'étape 2. Un exemple minimal avec curl ressemble à ceci :

curl "https://www.zohoapis.com/crm/v8/Leads/3652397000009851001" \
  -X GET \
  -H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

^[3]

Étape 4. Limitez éventuellement les champs renvoyés grâce au paramètre de requête fields.

Pour réduire la taille de la réponse, ajoutez ?fields= suivi d'une liste de noms de champs API séparés par des virgules. Par exemple, pour récupérer uniquement le nom et l'adresse e-mail d'un lead :

GET /crm/v8/Leads/3652397000009851001?fields=Last_Name,Email

Cela reprend le même paramètre fields utilisé dans les appels de liste et permet de garder votre réponse compacte. ^[3]

Étape 5. Analysez la réponse.

Un appel réussi renvoie un tableau data contenant un seul objet. Extrayez directement les champs dont vous avez besoin depuis cet objet. Par exemple, dans une réponse JSON, vous accéderiez à data[0].Last_Name ou data[0].Email. L'id de l'enregistrement est toujours présent dans la réponse, quels que soient les champs demandés. ^[3]

Étape 6. Traitez l'enregistrement dans Deluge (si vous utilisez des workflows ou des fonctions Zoho CRM).

Si vous appelez l'API depuis un script Deluge plutôt que depuis un système externe, utilisez la tâche invokeurl avec le même point de terminaison et le même en-tête OAuth. Stockez la réponse analysée dans une variable de type map, puis utilisez .get("fieldapiname") pour extraire les valeurs individuelles — le même modèle que celui utilisé avec d'autres API de produits Zoho. ^[2]

---

Erreurs courantes

• Nom API de module incorrect. Le nom du module dans l'URL doit correspondre exactement au nom API CRM, y compris la casse (par ex., Leads et non leads). Une discordance renvoie une erreur 404 ou INVALID_MODULE. ^[3]
• Jeton OAuth expiré ou manquant. Les jetons ont une durée de vie limitée. Si vous recevez une réponse 401 INVALID_TOKEN, actualisez votre jeton d'accès avant de réessayer. ^[3]
• Récupération d'un lead converti sans l'indicateur converted. Lors de la récupération de leads déjà convertis, le point de terminaison standard peut ne pas les renvoyer, sauf si vous incluez explicitement ?converted=true dans les appels basés sur des listes. Pour les recherches d'enregistrement unique, vérifiez que l'enregistrement existe toujours dans le module que vous interrogez. ^[3]
• Confusion entre les formats d'identifiant d'enregistrement. Les identifiants dans Zoho CRM sont de longues chaînes numériques. Transmettre un identifiant tronqué ou mal saisi entraînera une erreur d'enregistrement introuvable. Copiez toujours l'identifiant de manière programmatique plutôt que manuellement. ^[3]

---

Points à vérifier

• Confirmez que le tableau data de la réponse contient exactement un objet — s'il est vide, l'identifiant d'enregistrement n'existe pas dans ce module ou votre jeton ne dispose pas de la portée requise.
• Vérifiez que les noms API des champs dans les paramètres de champs du module CRM correspondent à ce que vous avez transmis dans le paramètre fields ; les noms d'affichage et les noms API diffèrent souvent.
• Assurez-vous que votre portée OAuth inclut ZohoCRM.modules.READ (ou l'équivalent spécifique au module) afin que le jeton soit autorisé à lire les enregistrements du module cible. ^[3]