Cómo obtener campos en Zoho

Recuperar campos en Zoho CRM requiere llamar al endpoint de API correcto con autenticación válida y el contexto de módulo o diseño adecuado — así es como hacerlo de forma fiable.

Por qué esto es importante

Cuando construyes integraciones, automatizaciones o informes personalizados, necesitas saber exactamente qué campos existen en un módulo o diseño de Zoho CRM. Sin los nombres de API de campo correctos, las consultas y los filtros fallarán con errores de "columna no válida". Entender cómo obtener campos de forma programática también te ayuda a evitar codificar nombres de campo que pueden diferir entre organizaciones.

Paso a paso

Paso 1. Asegúrate de que tu conexión OAuth está establecida y los tokens son válidos.

Antes de cualquier llamada a la API, tu integración debe disponer de un token de acceso válido para la organización de Zoho CRM de destino. La conexión se almacena junto con los valores refreshtoken, accesstoken, apidomain y tokenexpires_at. Si el token de acceso ha expirado, un flujo de actualización de token obtiene uno nuevo automáticamente usando el token de actualización almacenado y, a continuación, persiste el token actualizado en el registro de conexión. ^[3]

Paso 2. Identifica el centro de datos correcto para tu organización.

Zoho CRM está alojado en múltiples centros de datos. La URL base para CRM sigue el patrón https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}, donde {dc} es el sufijo del centro de datos (por ejemplo, com, eu, in, com.au). El centro de datos se infiere normalmente del api_domain devuelto durante OAuth — concretamente la parte que aparece después de zohoapis. en esa cadena de dominio. ^[1][5]

Paso 3. Determina si necesitas campos a nivel de módulo o a nivel de diseño.

Zoho CRM distingue entre campos asociados a un módulo completo y campos limitados a un diseño específico dentro de ese módulo. Si necesitas campos específicos de un diseño, primero debes conocer el layoutId del diseño al que apuntas. Los IDs de diseño se pueden recuperar desde el endpoint de diseños antes de proceder a la llamada de campos.

Paso 4. Llama al endpoint de campos para el diseño correspondiente.

Para recuperar campos limitados a un diseño concreto, realiza una solicitud GET a /api/v1/layouts/{layoutId}/fields, sustituyendo el identificador de diseño real. Se puede pasar un diccionario de parámetros de consulta opcionales (p) para filtrar o paginar los resultados. ^[4]

Un ejemplo mínimo en Python de esta llamada tiene el siguiente aspecto:

def get_layout_fields(self, layoutId: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/layouts/{layoutId}/fields", p, None)

^[4]

Paso 5. Confirma que los scopes de OAuth necesarios están configurados.

El token OAuth utilizado debe incluir los scopes de Zoho CRM apropiados. Los scopes necesarios para un acceso amplio a CRM incluyen ZohoCRM.modules.ALL y ZohoCRM.org.ALL, entre otros. Sin estos scopes, la API devolverá un error 401 o de permisos. ^[8]

Paso 6. Gestiona los errores de forma adecuada.

Si la API devuelve un mensaje de "columna no válida", normalmente significa que el nombre de API de campo proporcionado en una consulta posterior no coincide con lo que devolvió el endpoint de campos. Si se devuelve un estado 401, el token de acceso ha sido rechazado y el usuario debe volver a conectar su cuenta de Zoho. ^[6]

---

Errores comunes

• Centro de datos incorrecto: Usar crm.zoho.com cuando tu organización está en crm.zoho.eu provocará fallos de autenticación o respuestas vacías. Deriva siempre el centro de datos del api_domain almacenado durante OAuth. ^[5]
• layoutId ausente: El endpoint /api/v1/layouts/{layoutId}/fields requiere un identificador de diseño válido. Pasar un ID en blanco o incorrecto hará que la solicitud falle. ^[4]
• Tokens expirados: Si el token de acceso ha caducado y el flujo de actualización falla (por ejemplo, porque el token de actualización fue revocado), la instancia de la API devolverá None y no se recuperará ningún campo. Verifica siempre que el actualizador de tokens devuelve un token de acceso válido antes de continuar. ^[3]
• Scopes insuficientes: Si la concesión OAuth no incluyó ZohoCRM.modules.ALL o equivalente, las llamadas de recuperación de campos serán rechazadas. Revisa los scopes configurados y vuelve a autorizar si es necesario. ^[8]
• "Columna no válida" en consultas posteriores: Tras recuperar los campos, usa el nombre de API exacto (no la etiqueta de visualización) al construir filtros o consultas COQL. Una discrepancia provoca un error de "nombre de columna no válido". ^[6]

---

Qué verificar

• Validez del token: Confirma que el access_token almacenado está vigente y que el actualizador de tokens puede obtener uno nuevo correctamente si es necesario. ^[3]
• ID de diseño correcto: Verifica que el layoutId que estás pasando a /api/v1/layouts/{layoutId}/fields corresponde a un diseño real en el módulo de destino. ^[4]
• Cobertura de scopes: Comprueba que tu concesión OAuth incluye ZohoCRM.modules.ALL (o el scope mínimo requerido) para que el endpoint de campos sea accesible. ^[8]

---

*Beam Help ofrece soporte experto independiente para Zoho — no somos el soporte oficial de Zoho. Para problemas a nivel de plataforma, consulta siempre la documentación oficial de la API de Zoho CRM.*