Cómo recuperar servicios en Zoho

Recuperar servicios de Zoho a través de la capa de API requiere una conexión OAuth válida, un token de acceso activo y el tipo de aplicación correcto — si alguno de estos elementos falla, todas las llamadas posteriores devolverán None de forma silenciosa.

Por qué esto es importante

Cuando construyes automatizaciones o integraciones sobre Zoho CRM o Zoho Desk, cada llamada a una herramienta debe primero resolver una instancia de API funcional para el usuario autenticado. Si la búsqueda de la conexión falla, o el token ha expirado sin haberse renovado, no se devolverá ningún dato de servicio. Comprender la cadena de recuperación completa — desde la consulta a la base de datos, pasando por la renovación del token, hasta la instanciación de la API — te permite diagnosticar fallos rápidamente y construir integraciones más resilientes. Como soporte experto independiente para Zoho (no soporte oficial de Zoho), Beam Help documenta este flujo para que tu equipo pueda mantenerlo con confianza.

Paso a paso

Paso 1. Confirma que las variables de entorno están configuradas antes de intentar cualquier conexión. Como mínimo necesitas ZOHOCLIENTID, ZOHOCLIENTSECRET y OPENROUTERAPIKEY definidas en un archivo .env en la raíz del proyecto. También puedes establecer ZOHO_DC para apuntar a un centro de datos específico (por ejemplo eu, in, com.au o jp; el valor predeterminado es com). ^[8]

Paso 2. Asegúrate de que el servidor esté en ejecución antes de cualquier intento de recuperación. Inícialo con:

python3 server.py

Puedes confirmar que está escuchando ejecutando lsof -i :8080. ^[8]

Paso 3. Recupera la conexión de Zoho almacenada para un usuario determinado llamando a getzohoconnection(userid). Esta función consulta la tabla zohoconnections en busca del user_id correspondiente. Si no se encuentra ninguna fila, la función devuelve None y no es posible realizar ninguna recuperación adicional. ^[3]

Paso 4. La función de conexión gestiona automáticamente la expiración del token. Compara la hora actual con tokenexpiresat, aplicando un margen de renovación anticipada de 120 segundos para reducir los errores 401 durante las solicitudes. Cuando se necesita una renovación, llama a ZohoOAuth.refreshtokens() con el refreshtoken almacenado y, a continuación, escribe el nuevo accesstoken y el tokenexpires_at actualizado en la base de datos antes de devolver el objeto de conexión renovado. ^[3]

Paso 5. Pasa la conexión resuelta a getzohoapi(userid, apptype), especificando "crm" o "desk" como apptype. Esta función llama a getzoho_connection internamente, por lo que si la conexión no existe devuelve (None, None) de inmediato. ^[1]

Paso 6. Para Zoho Desk específicamente, la función también requiere un orgid. Lee deskorgid del registro de conexión. Si ese campo está vacío, descubre automáticamente la organización llamando a api.getall_organizations(), extrae el id del primer elemento de la lista data devuelta y lo persiste para llamadas futuras. ^[1]

Paso 7. Para Zoho CRM, puedes verificar que la conexión funciona comprobando que el crmorgid almacenado está presente en la tabla zohoconnections. El conjunto de pruebas hace esto obteniendo la fila más reciente y pasando crmorg_id a un paso de validación de organización en entorno de pruebas. ^[5]

Paso 8. Una vez que tienes una instancia de API activa, las llamadas a herramientas se despachan a través de executetoolwithrepair(), que acepta el objeto api, el apptype, un nombre de herramienta tool como cadena de texto y un diccionario params. La capa de streaming emite un evento de estado — "Calling Zoho tool: <toolname>..." — antes de cada ejecución para que puedas observar el progreso en tiempo real. ^[2]

Paso 9. Si necesitas recuperar detalles del usuario o de la organización de forma independiente a una llamada de herramienta, usa ZohoOAuth.getuserinfo(accesstoken). Esta función accede a https://accounts.zoho.<DC>/oauth/user/info con un encabezado de token Bearer y devuelve campos como ZUID (ID de usuario), Email e identificadores de organización. Ten en cuenta que los nombres de los campos varían según el centro de datos — la función prueba orgid, organization_id y ZGID en secuencia antes de recurrir al ID de usuario. ^[4]

Errores comunes

• orgid ausente en llamadas a Desk. Si deskorg_id no está almacenado y la llamada de autodescubrimiento también falla, el cliente de la API de Desk se inicializará con una cadena vacía, lo que provocará que todas las solicitudes posteriores a Desk fallen silenciosamente. Verifica siempre que el ID de organización quede persistido tras la primera conexión exitosa. ^[1]
• La renovación del token no devuelve ningún accesstoken. El cierre tokenrefresher comprueba la clave "accesstoken" en la respuesta de renovación; si está ausente, el renovador devuelve None y la instancia de API usará un token obsoleto. Esto generalmente significa que el propio refreshtoken ha expirado y el usuario debe volver a conectarse mediante el flujo OAuth. ^[1]
• Discrepancia de centro de datos. La variable de entorno ZOHO_DC debe coincidir con la región donde se creó la cuenta de Zoho. Una discrepancia provoca que las llamadas OAuth y de API lleguen al endpoint incorrecto, generando errores de autenticación incluso con credenciales válidas. ^{[4] [8]}
• Autenticación con herramientas de navegador. Si usas herramientas basadas en navegador (p. ej. browsernavigateandscreenshot), la sesión del navegador se autentica de forma independiente a la sesión de API. Una sesión de navegador expirada devuelve un error actionrequired que solicita una llamada POST /api/browser/login en lugar de una renovación de token estándar. ^[6]

Qué verificar

• Confirma que existe una fila en zohoconnections para el userid objetivo y que tokenexpiresat es una marca de tiempo Unix futura válida. ^[3]
• Verifica que deskorgid (para Desk) o crmorgid (para CRM) esté completado en el registro de conexión para que la instancia de API se inicialice con el contexto de organización correcto. ^{[1] [5]}
• Tras cualquier cambio en el entorno, reinicia el servidor (pkill -f "python3 server.py"; sleep 1; python3 server.py) y vuelve a ejecutar una comprobación de conexión para asegurarte de que las nuevas variables están cargadas. ^[8]