Cómo recuperar notificaciones en Zoho

Recuperar notificaciones en Zoho CRM mediante la API requiere los scopes de OAuth correctos y un token de acceso válido y actualizado — si tienes esos dos elementos en orden, el resto fluye de manera natural.

Por qué esto es importante

Cuando necesitas leer, crear, actualizar o eliminar notificaciones de CRM de forma programática — por ejemplo, para construir un panel de alertas personalizado o sincronizar datos de notificaciones con una herramienta de terceros — debes asegurarte de que tu cliente OAuth esté autorizado con los scopes de permisos correctos y de que tu flujo de tokens gestione la expiración de forma adecuada. Sin esta base, cada solicitud de notificación devolverá un error 401 o un error de permisos antes de llegar siquiera a los datos.

> Beam Help es soporte experto independiente para Zoho — no somos el soporte oficial de Zoho.

---

Paso a paso

Paso 1. Confirma que tu cliente OAuth incluye los scopes específicos de notificaciones antes de generar o actualizar cualquier token. Los cuatro scopes que necesitas son ZohoCRM.notifications.READ, ZohoCRM.notifications.CREATE, ZohoCRM.notifications.UPDATE y ZohoCRM.notifications.DELETE. Si solo quieres recuperar (leer) notificaciones, ZohoCRM.notifications.READ es el scope mínimo requerido. ^[1]

Paso 2. Asegúrate de que también esté presente tu conjunto de scopes de CRM más amplio. Los scopes de notificaciones coexisten con otros scopes de CRM como ZohoCRM.modules.ALL, ZohoCRM.org.ALL y ZohoCRM.coql.READ. Todos estos deben declararse juntos al registrar o actualizar tu cliente OAuth, de modo que un único token cubra todas las operaciones que necesita tu integración. ^[1]

Paso 3. Establece una conexión válida para el usuario antes de realizar cualquier llamada de notificaciones. Tu backend debe buscar el registro de conexión almacenado (token de acceso, token de actualización, marca de tiempo de expiración) para el usuario correspondiente. Si no existe ningún registro, el usuario debe volver a autenticarse mediante el flujo OAuth antes de que pueda realizarse cualquier llamada a la API. ^[3]

Paso 4. Implementa la actualización proactiva del token para que tu token de acceso siempre sea válido en el momento de la solicitud. Un patrón fiable es verificar si el tiempo actual está dentro de los 120 segundos previos a la marca de tiempo de expiración del token — si es así, llama al endpoint de actualización de inmediato, almacena el nuevo accesstoken y el tokenexpires_at actualizado en tu base de datos, y luego procede con la solicitud de notificaciones usando el token renovado. ^[3]

Paso 5. Si se necesita una actualización durante la solicitud (por ejemplo, en un proceso de larga duración donde el token expira a mitad del proceso), tu lógica de actualización debe obtener el refreshtoken más reciente de la base de datos, llamar a ZohoOAuth.refreshtokens(), verificar que accesstoken esté presente en la respuesta, y persistir los valores actualizados antes de devolver el nuevo token al llamador. Si accesstoken está ausente en la respuesta de actualización, trata la actualización como fallida y muestra un error en lugar de continuar con un token obsoleto. ^[2]

Paso 6. Instancia tu cliente de la API de Zoho CRM usando el token de acceso resuelto y el dominio de API correcto almacenado en el registro de conexión. Pasa el callback de actualización del token al cliente para que pueda gestionar la expiración automáticamente durante operaciones de recuperación de notificaciones paginadas o de múltiples pasos. ^[2]

Paso 7. Con un cliente válido disponible, llama a la herramienta o endpoint de notificaciones correspondiente. En un contexto de chat/agente, la capa de ejecución de herramientas lo encapsula como una llamada de herramienta con nombre (p. ej., una herramienta de tipo get_notifications), pasa los parámetros relevantes y transmite actualizaciones de estado al llamador mientras la solicitud está en curso. ^[6]

Paso 8. Gestiona el caso en que el objeto de la API no pudo inicializarse — por ejemplo, si la cuenta de Zoho del usuario no está conectada o si la actualización falló. En ese escenario, muestra un mensaje claro como "Zoho is not connected for this app. Please reconnect." en lugar de fallar silenciosamente o devolver datos vacíos. ^[4]

---

Errores comunes

• Scopes de notificaciones ausentes en el momento del registro. Si añades ZohoCRM.notifications.READ a tu configuración pero el cliente OAuth fue registrado originalmente sin él, los tokens de actualización existentes no incluirán el nuevo scope. Debes volver a autorizar (ejecutar de nuevo el flujo de consentimiento OAuth) para obtener un token que incluya el conjunto de scopes actualizado. ^[1]

• Tokens obsoletos que generan errores 401 silenciosos. Si tu lógica de actualización solo se activa *después* de una solicitud fallida en lugar de *antes*, verás errores 401 intermitentes en la primera llamada de una sesión. La ventana de actualización preventiva de 120 segundos está diseñada específicamente para evitar esta condición de carrera. ^[3]

• Token de actualización no guardado en la base de datos. Tras una actualización de token exitosa, tanto accesstoken como tokenexpiresat deben escribirse de nuevo en la tabla zohoconnections. No persistir estos valores significa que la siguiente solicitud intentará actualizarse de nuevo con el mismo token de actualización (posiblemente ya consumido), lo que puede invalidar la sesión por completo. [^2, ^3]

• Uso del apptype incorrecto. La función getzohoapi acepta un parámetro apptype ("crm" o "desk"). La recuperación de notificaciones para Zoho CRM requiere app_type="crm". Pasar "desk" enrutará la solicitud al cliente de Zoho Desk, que utiliza un conjunto de scopes completamente diferente y una ruta de resolución de org-ID distinta. ^[2]

---

Qué verificar

• Los scopes están presentes y activos: Verifica que ZohoCRM.notifications.READ (y cualquier scope de escritura que necesites) aparezca en tu cliente OAuth registrado *y* en el token que tu aplicación está usando actualmente — no solo en tu archivo de configuración. ^[1]
• La actualización del token se persiste correctamente: Después de cualquier evento de actualización, consulta tu tabla zohoconnections y confirma que accesstoken y tokenexpiresat reflejan los valores recién emitidos, no los anteriores. ^[3]
• El registro de conexión existe para el usuario: Antes de ejecutar cualquier recuperación de notificaciones, confirma que existe una fila en zohoconnections para el userid objetivo; si falta, el cliente de la API será None y todas las llamadas posteriores fallarán silenciosamente. [^2, ^4]