Cómo recuperar un registro individual en Zoho

Recuperar un registro individual en Zoho CRM a través de la API significa apuntar a una entrada específica por su ID de registro único, devolviendo solo los datos que necesitas sin tener que obtener una lista completa.

Por qué esto es importante

Cuando construyes integraciones o automatizaciones, obtener una lista completa de registros solo para leer uno es ineficiente y lento. Identificar un registro por su ID mantiene las llamadas a la API ligeras, evita alcanzar los límites de velocidad y hace que tus flujos de trabajo basados en Deluge o REST sean mucho más fáciles de mantener. Este patrón es especialmente común cuando un disparador (como un flujo de trabajo o un webhook) ya te proporciona un ID de registro y simplemente necesitas enriquecer o validar los datos de ese registro.

> Nota: Beam Help es soporte experto independiente para Zoho — no somos el soporte oficial de Zoho.

---

Paso a paso

Paso 1. Obtén un token de acceso OAuth válido para Zoho CRM.

Antes de cualquier llamada a la API, tu cliente debe intercambiar sus credenciales por un token de portador. El token se pasa en cada encabezado de solicitud como Authorization: Zoho-oauthtoken <your_token>. Sin esto, la API de CRM rechazará la solicitud. ^[3]

Paso 2. Identifica el módulo y el ID del registro que deseas recuperar.

Zoho CRM organiza los datos en módulos como Leads, Contacts, Accounts, Deals, entre otros. Cada registro dentro de un módulo tiene un id numérico único (por ejemplo, 3652397000009851001). Debes conocer tanto el nombre del módulo como el ID del registro antes de realizar la llamada. ^[3]

Paso 3. Construye la solicitud GET al endpoint de registro individual.

La API v8 de Zoho CRM expone registros individuales en:

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

Reemplaza {Module} con el nombre de API del módulo (p. ej., Leads, Contacts) y {record_id} con el ID numérico del Paso 2. Un ejemplo mínimo con curl se ve así:

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

^[3]

Paso 4. Opcionalmente, limita los campos devueltos usando el parámetro de consulta fields.

Para reducir el tamaño del payload, añade ?fields= seguido de una lista separada por comas de nombres de campos de la API. Por ejemplo, para recuperar solo el apellido y la dirección de correo electrónico de un lead:

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

Esto refleja el mismo parámetro fields utilizado en las llamadas de lista y mantiene tu respuesta compacta. ^[3]

Paso 5. Analiza la respuesta.

Una llamada exitosa devuelve un array data que contiene un único objeto. Extrae los campos que necesitas directamente de ese objeto. Por ejemplo, en una respuesta JSON accederías a data[0].Last_Name o data[0].Email. El id del registro siempre está presente en la respuesta independientemente de los campos que hayas solicitado. ^[3]

Paso 6. Gestiona el registro dentro de Deluge (si usas flujos de trabajo o funciones de Zoho CRM).

Si estás llamando a la API desde un script de Deluge en lugar de un sistema externo, usa la tarea invokeurl con el mismo endpoint y encabezado OAuth. Almacena la respuesta analizada en una variable de mapa y luego usa .get("fieldapiname") para extraer valores individuales — el mismo patrón utilizado al trabajar con otras APIs de productos Zoho. ^[2]

---

Errores comunes

• Nombre de API del módulo incorrecto. El nombre del módulo en la URL debe coincidir exactamente con el nombre de API del CRM, incluidas las mayúsculas (p. ej., Leads y no leads). Una discrepancia devuelve un error 404 o INVALID_MODULE. ^[3]
• Token OAuth caducado o ausente. Los tokens tienen una vida útil limitada. Si recibes una respuesta 401 INVALID_TOKEN, actualiza tu token de acceso antes de volver a intentarlo. ^[3]
• Solicitar un lead convertido sin el indicador converted. Al obtener leads que ya han sido convertidos, el endpoint estándar puede no devolverlos a menos que incluyas explícitamente ?converted=true en las llamadas basadas en listas. Para búsquedas de registros individuales, confirma que el registro aún existe en el módulo que estás consultando. ^[3]
• Confundir formatos de ID de registro. Los IDs en Zoho CRM son cadenas numéricas largas. Pasar un ID truncado o escrito incorrectamente resultará en un error de registro no encontrado. Copia siempre el ID de forma programática en lugar de hacerlo manualmente. ^[3]

---

Qué verificar

• Confirma que el array data de la respuesta contiene exactamente un objeto — si está vacío, el ID del registro no existe en ese módulo o tu token carece del alcance requerido.
• Verifica los nombres de campo de la API en la configuración de campos del módulo del CRM para asegurarte de que coinciden con lo que pasaste en el parámetro fields; los nombres de visualización y los nombres de API suelen ser diferentes.
• Comprueba que tu alcance OAuth incluya ZohoCRM.modules.READ (o el equivalente específico del módulo) para que el token esté autorizado a leer los registros del módulo de destino. ^[3]