Cómo obtener pipelines en Zoho

Recuperar los pipelines en Zoho CRM es sencillo una vez que tu conexión OAuth está establecida — puedes consultar la API de módulos del CRM para obtener los datos de pipeline (etapas de negocio) directamente desde tu cuenta.

Por qué esto es importante

Los equipos de ventas dependen de los pipelines para hacer seguimiento de los negocios a través de cada etapa del embudo. Si estás construyendo una integración, automatizando informes o utilizando una herramienta como el Zoho AI Pilot Engine de Beam Help, necesitarás obtener los datos de pipeline y módulos de forma programática. Comprender los scopes correctos y el flujo de la API garantiza que obtengas datos precisos y en tiempo real, en lugar de instantáneas desactualizadas.

Paso a paso

Paso 1. Configura tus credenciales de la API de Zoho visitando la Zoho API Console y creando una Aplicación basada en servidor. Anota tu Client ID y tu Client Secret — los necesitarás ambos para autenticar cualquier solicitud a la API.^[1]

Paso 2. Al registrar tu aplicación, asegúrate de incluir el scope ZohoCRM.modules.ALL junto con ZohoCRM.settings.ALL y ZohoCRM.users.ALL. El scope de módulos es el que otorga acceso a los datos de pipeline y etapas de negocio dentro de Zoho CRM.^[1]

Paso 3. Configura tu URI de redirección para que coincida exactamente con la registrada en la API Console. Si estás ejecutando en local, normalmente es http://localhost:8080/api/auth_callback. Una discrepancia aquí provocará un error de redirección OAuth y bloqueará el intercambio de tokens.^[1]

Paso 4. Almacena tus credenciales de forma segura en un archivo .env en la raíz del proyecto. Las variables mínimas requeridas son ZOHOCLIENTID, ZOHOCLIENTSECRET y tu configuración de centro de datos (ZOHO_DC), que por defecto es com, pero puede establecerse como eu, in, com.au o jp según dónde esté alojada tu cuenta de Zoho.^[1]

Paso 5. Establece la conexión OAuth. Una vez que tu servidor esté en ejecución, haz clic en Connect Zoho CRM en la interfaz y completa el flujo de autorización. El sistema almacena tu token de acceso y token de actualización para que las solicitudes posteriores se gestionen automáticamente.^[2]

Paso 6. La capa de conexión actualiza automáticamente tu token de acceso cuando faltan 120 segundos para su expiración, por lo que las consultas de pipeline de larga duración no fallarán a mitad de la solicitud con un error 401. Esto se gestiona de forma transparente — no necesitas administrar la rotación de tokens manualmente.^[6]

Paso 7. Para recuperar datos de pipeline, realiza una consulta en lenguaje natural como *«muéstrame todos los negocios»* o *«lista las oportunidades abiertas»*. Internamente, esto se traduce en una llamada search_records al módulo Deals, que contiene las etapas del pipeline para cada registro.^[7]

Paso 8. Si quieres un recuento de registros en cada etapa del pipeline, puedes preguntar *«cuántos negocios tengo»* — esto se enruta a la herramienta getrecordcount con el módulo Deals como parámetro, dándote una cifra rápida del volumen del pipeline.^[7]

Paso 9. Para enlaces directos a registros, el patrón de URL del CRM sigue https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. Sustituye el código de tu centro de datos y el nombre del módulo correspondiente (p. ej., Deals) para construir enlaces profundos a registros específicos del pipeline.^[5]

Errores comunes

• URI de redirección incorrecta. La URI de redirección en tu .env y en la Zoho API Console debe ser idéntica carácter por carácter. Incluso una diferencia en una barra diagonal al final provocará que el callback OAuth falle.^[1]
• Scope de módulo faltante. Omitir ZohoCRM.modules.ALL de tu lista de scopes significa que los endpoints de pipeline y etapas de negocio devolverán errores de permisos. Incluye siempre los tres scopes recomendados durante el registro de la aplicación.^[1]
• Centro de datos incorrecto. Si tu cuenta de Zoho está en el centro de datos de la UE o India y ZOHODC se deja como com, las llamadas a la API llegarán al endpoint incorrecto y devolverán fallos de autenticación. Establece ZOHODC para que coincida con la región de tu cuenta.^[1]
• Estado de base de datos desactualizado. Si encuentras errores inesperados tras cambiar credenciales o volver a autorizar, eliminar el archivo SQLite local (data/zpilot.sqlite) y reiniciar el servidor fuerza un estado limpio.^[2]

Qué verificar

• Confirma que ZohoCRM.modules.ALL y ZohoCRM.settings.ALL aparecen ambos en los scopes aprobados de tu aplicación en la Zoho API Console.^[1]
• Verifica que ZOHO_DC en tu .env coincide con el centro de datos que aparece en la URL de tu cuenta de Zoho CRM (p. ej., eu para crm.zoho.eu).^[1]
• Tras conectar, prueba la ruta de actualización del token esperando a un estado próximo a la expiración o comprobando que la tabla zohoconnections se actualiza con un nuevo accesstoken y tokenexpiresat.^[6]

---

*Beam Help es soporte experto independiente para Zoho — no somos el soporte oficial de Zoho, y esta guía está basada en nuestra propia experiencia de implementación.*