Cómo recuperar casos en Zoho

Recuperar casos en Zoho Desk requiere una conexión OAuth válida, un ID de organización resuelto y el cliente de API correcto inicializado para el tipo de aplicación desk — todo lo cual nuestra integración gestiona automáticamente una vez que tu conexión está establecida.

Por qué esto es importante

Los casos de Zoho Desk (tickets de soporte) se encuentran bajo un contexto de organización específico, por lo que cualquier llamada de recuperación debe incluir el org_id correcto junto con un token de acceso activo. Si tu token ha expirado o el ID de organización nunca se almacenó, la llamada a la API fallará silenciosamente o devolverá un error de autorización. Comprender el flujo completo te ayuda a diagnosticar problemas rápidamente — y como Beam Help (soporte experto independiente para Zoho, no soporte oficial de Zoho), queremos que ese flujo sea transparente.

Paso a paso

Paso 1. Confirma que existe un registro de conexión de Zoho para tu cuenta de usuario. El sistema busca tus credenciales en la tabla zohoconnections usando tu userid. Si no se encuentra ningún registro, el proceso de recuperación no puede comenzar y se devuelve None inmediatamente — necesitarás reconectarte mediante OAuth antes de continuar. ^[2]

Paso 2. Asegúrate de que tu token de acceso sigue siendo válido. La capa de conexión comprueba si el tiempo actual está dentro de los 120 segundos del valor almacenado en tokenexpiresat. Si es así, se activa una actualización proactiva usando tu refreshtoken antes de solicitar cualquier dato de casos, reduciendo la posibilidad de un error 401 a mitad de la solicitud. El accesstoken actualizado y la nueva fecha de expiración se escriben automáticamente en la base de datos. ^[2]

Paso 3. Inicializa el cliente de API con apptype establecido en "desk". Esto indica al sistema que instancie un ZohoDeskClient en lugar de la variante de CRM. El cliente se construye usando tu apidomain almacenado, el accesstoken actual, tu deskorgid y un callback tokenrefresher que puede obtener silenciosamente un nuevo token durante la sesión si es necesario. ^[1]

Paso 4. Permite que el sistema descubra automáticamente tu ID de organización si aún no está almacenado. Cuando deskorgid está vacío, la integración llama a getallorganizations y lee el campo id del primer elemento de la lista data devuelta. Este valor descubierto se persiste para que las llamadas futuras omitan el paso de descubrimiento por completo. ^[1]

Paso 5. Con el cliente listo, ejecuta tu llamada de herramienta para recuperar casos. En el flujo de chat o planificación, el nombre de herramienta apropiado (por ejemplo, getrecords apuntando al módulo Cases) se pasa a executetoolwithrepair, que ejecuta la consulta y devuelve resultados estructurados. El sistema también emite un mensaje de estado como "Calling Zoho tool: <toolname>..." para que puedas confirmar que la llamada está en curso. [^3,5]

Paso 6. Inspecciona el payload devuelto. Los resultados exitosos se devuelven como un diccionario que contiene los registros de casos. El sistema además genera enlaces contextuales usando tus valores dc (centro de datos), deskorgid y desk_portal para que puedas navegar directamente a los registros correspondientes en la interfaz de Zoho Desk. ^[3]

Paso 7. Si estás probando el flujo de recuperación directamente (sin pasar por la interfaz de chat), la ruta de llamada directa obtiene el registro de conexión creado más recientemente de la base de datos y construye su propio cierre token_refresher antes de invocar la herramienta. Confirma que existe al menos una fila de conexión antes de ejecutar pruebas directas. ^[4]

Errores comunes

• orgid faltante: Si deskorg_id es una cadena vacía y la llamada de auto-descubrimiento también falla (por ejemplo, debido a permisos OAuth insuficientes), todas las llamadas posteriores a la API de Desk serán rechazadas. Verifica que tus permisos OAuth incluyan acceso al endpoint de organizaciones de Desk. ^[1]
• Token de actualización obsoleto: El método refreshtokens espera un refreshtoken válido en el cuerpo de la solicitud junto con tu clientid y clientsecret. Si el token de actualización ha sido revocado (por ejemplo, el usuario volvió a autorizar desde una sesión diferente), la respuesta contendrá una clave error en lugar de access_token, y la conexión se marcará como inutilizable. ^[6]
• apptype incorrecto: Pasar apptype="crm" cuando pretendes recuperar casos de Desk instanciará el cliente de CRM en su lugar, y los endpoints específicos de casos no estarán disponibles. Confirma siempre que el parámetro app_type coincide con el producto que estás consultando. ^[1]
• Sin fila de conexión en pruebas directas: El arnés de prueba de llamada directa selecciona la fila de conexión insertada más recientemente. Si la base de datos está vacía o la fila fue eliminada, la llamada devuelve {"error": "No Zoho connection found"} inmediatamente. ^[4]

Qué verificar

• Verifica que zohoconnections contenga una fila para tu usuario con un deskorgid no vacío y un valor tokenexpires_at en el futuro. [^1,2]
• Confirma que tus permisos OAuth fueron concedidos con accesstype=offline y prompt=consent para que se incluya un refreshtoken en la respuesta inicial del intercambio de tokens. ^[6]
• Tras una recuperación exitosa, comprueba que el payload devuelto contenga una lista data con al menos un objeto de caso, y que los enlaces de Desk generados hagan referencia al subdominio desk_portal correcto para tu cuenta. ^[3]