Cómo recuperar una variable específica en Zoho CRM

Recuperar una variable específica en Zoho CRM te permite pasar valores dinámicos en tiempo de ejecución a consultas y componentes — manteniendo tus búsquedas de datos flexibles sin codificar criterios de forma fija.

Por qué esto es importante

Cuando construyes consultas en el Developer Hub de Zoho CRM, a menudo necesitas filtrar o parametrizar resultados basándote en contexto que cambia en tiempo de ejecución — como el usuario actual, un ID de registro seleccionado, o un rango de fechas. Las variables resuelven esto actuando como marcadores de posición que se resuelven cuando la consulta se ejecuta realmente. Sin ellas, necesitarías una consulta separada para cada combinación de filtro posible, lo que rápidamente se vuelve inmanejable. ^[6]

Paso a paso

Paso 1. Navega a la sección Consultas yendo a Configuración → Developer Hub → Consultas. Se abrirá la ventana Consultas, mostrando cualquier consulta existente que hayas configurado. ^[6]

Paso 2. Abre la consulta en la que deseas usar una variable, o haz clic para crear una nueva. Elige el tipo de fuente apropiado — Módulo, COQL, o REST API — dependiendo de dónde vivan tus datos. Cada tipo de fuente determina cómo y dónde se pueden insertar variables. ^[6]

Paso 3. Declara tu variable directamente dentro de la definición de la consulta. Las variables deben escribirse entre llaves dobles usando el formato {{VARIABLE_NAME}}. Puedes colocarlas dentro de filtros de criterios, condiciones de sentencias COQL, valores de campos, o rutas y encabezados de endpoints REST API — en cualquier lugar donde se necesite un valor dinámico. ^[6]

Paso 4. Guarda la consulta. Una vez guardada, el marcador de posición de variable se registra y está listo para ser mapeado. ^[6]

Paso 5. Asocia la consulta con un componente (por ejemplo, un elemento Canvas o un widget de panel). Durante el paso de asociación, se te pedirá que mapees cada variable declarada al campo o fuente de entrada relevante. Este mapeo es lo que le dice a Zoho CRM qué valor real sustituir en {{VARIABLE_NAME}} en tiempo de ejecución. ^[6]

Paso 6. Prueba la consulta activando el componente o ejecutando la consulta en contexto. El sistema resolverá cada marcador de posición {{VARIABLE_NAME}} con el valor en tiempo de ejecución mapeado y devolverá resultados filtrados en consecuencia. ^[6]

Extrayendo un valor de variable de una estructura de datos anidada

Si tu variable contiene datos estructurados — por ejemplo, una carga JSON que llega de una integración externa como Calendly — es posible que necesites analizar un campo específico antes de mapearlo a un campo CRM. Un escenario común es un número de teléfono enterrado dentro de un objeto anidado como:

"questions_and_answers": {
  "question": "Phone number",
  "answer": "0612345678",
  "position": 0
}

En este caso, la variable sin procesar no puede mapearse directamente a un campo de teléfono CRM. Necesitarías extraer la clave answer de la carga primero — típicamente usando un paso de transformación en tu flujo de integración (como una función de Zoho Flow o una función personalizada) — antes de pasar el valor limpio al campo CRM. ^[2]

Errores comunes

• Sintaxis incorrecta: Las variables que no están envueltas en llaves dobles ({{VARIABLE_NAME}}) serán tratadas como cadenas literales en lugar de marcadores de posición dinámicos, causando que las consultas no devuelvan resultados o lancen errores. Siempre confirma el formato exacto. ^[6]
• Variables sin mapear en el momento de la asociación: Si declaras una variable en una consulta pero olvidas mapearla cuando asocias la consulta con un componente, el valor en tiempo de ejecución estará vacío y tu consulta probablemente devolverá resultados inesperados. Verifica que cada variable tenga un mapeo correspondiente. ^[6]
• Valores JSON anidados: Cuando una variable contiene un objeto complejo (como una carga de webhook de Calendly), no puedes mapear una propiedad anidada directamente. Primero debes extraer el valor específico usando una transformación o función personalizada antes de que pueda rellenar un campo CRM limpiamente. ^[2]
• Restricciones de tipo de fuente: No todos los posicionamientos de variables están disponibles para cada tipo de fuente. Por ejemplo, las consultas de fuente REST API permiten variables en URLs de endpoints y encabezados, mientras que las consultas COQL las usan dentro de la sentencia de consulta misma. Confirma qué posicionamientos son válidos para tu fuente elegida. ^[6]

Qué verificar

• Verifica que cada {{VARIABLE_NAME}} en tu consulta esté correctamente mapeado a un campo o fuente de entrada cuando la consulta se asocia con un componente. ^[6]
• Confirma que el valor de variable que se pasa en tiempo de ejecución sea el tipo de dato correcto esperado por el campo CRM de destino (por ejemplo, una cadena simple para un número de teléfono, no un objeto JSON). ^[2]
• Después de la ejecución, revisa la respuesta de la consulta para asegurar que los datos devueltos coincidan con el resultado filtrado esperado — no el conjunto de datos completo sin filtrar. ^[6]

---

*Beam Help es un recurso de soporte experto independiente para productos Zoho y no es soporte oficial de Zoho. Para problemas a nivel de plataforma, siempre verifica con la documentación propia de Zoho.*