Las variables en las Consultas de Zoho CRM te permiten inyectar valores dinámicos en tiempo de ejecución, haciendo que una sola consulta guardada sea reutilizable en muchos contextos diferentes sin necesidad de reescribirla cada vez.
Por qué esto es importante
Cuando construyes una consulta en Zoho CRM, los valores de filtro codificados de forma fija limitan su reutilización. Las variables resuelven esto actuando como marcadores de posición que se rellenan en el momento en que se ejecuta la consulta — por ejemplo, pasando un ID de Contacto específico o un valor de Etapa desde un componente Canvas o una llamada a la API. Entender cómo declararlas y usarlas correctamente ahorra un tiempo de desarrollo significativo y mantiene tu biblioteca de consultas ordenada. [5]
---
Paso a paso
Paso 1. Navega a la sección de Consultas yendo a Configuración → Centro de Desarrolladores → Consultas. Se abrirá la ventana de Consultas, mostrando las consultas existentes que ya hayas creado. [2]
Paso 2. Haz clic en Agregar Consulta para comenzar a crear una nueva consulta. En el cuadro emergente Crear Consulta, introduce un Nombre de Consulta y un Nombre de API, luego haz clic en Siguiente. [2]
Paso 3. En Configuración, el tipo de fuente predeterminado es Módulo de Zoho CRM. Si necesitas un tipo de fuente diferente (como COQL o REST API), haz clic en Cambiar para cambiarlo. Selecciona el módulo de CRM que deseas consultar. Si el módulo contiene campos de búsqueda, puedes incluir módulos relacionados mediante el menú desplegable Módulo Relacionado — ten en cuenta que aquí se permite un máximo de dos campos de módulo relacionado. [2]
Paso 4. En el menú desplegable Campos, selecciona los campos que deseas que devuelva la consulta. Puedes seleccionar hasta 50 campos en una sola consulta. [2]
Paso 5. En Criterios, elige cómo deseas filtrar los registros. Las opciones son Ninguno (sin filtro), filtrar por ID de Registro, o aplicar Criterios personalizados usando comparadores combinados con operadores AND/OR. Aquí es donde las variables se vuelven esenciales: en lugar de escribir un valor fijo para un criterio, elige la opción de valor dinámico. Un valor dinámico indica que los datos reales se proporcionarán cuando la consulta se ejecute en otro lugar de tu configuración de CRM. [2]
Paso 6. Declara tu variable usando la sintaxis requerida. Donde quieras un valor dinámico — dentro de un campo de criterio, una declaración COQL, un endpoint de REST API o un valor de parámetro — escribe el nombre de la variable entre dobles llaves: {{VARIABLE_NAME}}. Este es el único formato aceptado; cualquier desviación impedirá que la variable sea reconocida en tiempo de ejecución. [1][5]
Paso 7. Las variables son compatibles en múltiples ubicaciones de consulta: valores de criterios, declaraciones COQL, URLs de endpoints y otros campos de parámetros. Cuando posteriormente asocies la consulta con un componente como una vista Canvas, se te pedirá que mapees cada variable declarada al campo o fuente de datos apropiada para que el valor en tiempo de ejecución pueda pasarse correctamente. [5]
Paso 8. Una vez que tu consulta y las variables estén configuradas, haz clic para guardar. Puedes volver a la consulta en cualquier momento desde la pestaña Consultas. Para ajustar la estructura de la respuesta, pasa el cursor sobre la consulta, haz clic en el icono de tres puntos y selecciona Gestionar Esquema — esto te permite editar los tipos de campo y las etiquetas en la salida de la consulta sin reescribirla. [1]
---
Errores comunes
- Sintaxis de variable incorrecta. Las variables deben escribirse como
{{VARIABLE_NAME}}— las llaves simples, los corchetes o cualquier otro formato no funcionarán. Verifica cada marcador de posición antes de guardar. [1][5] - Variables sin mapear al momento de la asociación. Si adjuntas una consulta que contiene variables a un componente Canvas u otra función de CRM pero olvidas mapear cada variable a un campo de origen, la consulta fallará en tiempo de ejecución porque no se proporciona ningún valor. Verifica siempre el paso de mapeo después de asociar una consulta. [5]
- Superar los límites de campos o búsquedas. Seleccionar más de 50 campos o más de dos búsquedas de módulos relacionados hará que la configuración de la consulta sea rechazada. Planifica la selección de campos antes de crear los criterios. [2]
- Requisitos previos de la fuente REST API. Si estás usando un tipo de fuente REST API en lugar de un Módulo de CRM, primero debes agregar el host externo a Dominios de Confianza y añadir a la lista blanca las IPs de Zoho CRM en tu servidor de retransmisión antes de que la fuente pueda ser validada y guardada. [5]
---
Qué verificar
- La sintaxis de las variables es correcta — confirma que cada marcador de posición dinámico en tu consulta sigue el formato de dobles llaves
{{VARIABLE_NAME}}antes de guardar. [1] - Las variables están mapeadas — después de asociar la consulta con un Canvas u otro componente, abre la configuración de mapeo y verifica que cada variable se resuelva a un campo de datos activo. [5]
- El esquema refleja tus necesidades — usa Gestionar Esquema para confirmar que los tipos de campo y las etiquetas en la respuesta de la consulta coinciden con lo que espera el componente que la consume, especialmente si has editado el esquema después de la creación inicial. [1]
---
*Beam Help es un recurso de soporte experto independiente para los productos de Zoho y no es el soporte oficial de Zoho. Para problemas a nivel de plataforma, siempre abre un ticket directamente con Zoho.*