Cómo recuperar la línea de tiempo en Zoho

Recuperar una línea de tiempo en Zoho requiere un token de acceso OAuth válido y una conexión correctamente configurada con la API de Zoho; una vez que ambos estén en orden, tu integración puede invocar las herramientas correspondientes para obtener los datos de la línea de tiempo de cualquier módulo compatible.

Por qué esto es importante

Los datos de la línea de tiempo te ofrecen una vista cronológica de la actividad asociada a un registro, lo cual resulta útil para auditar cambios, revisar el historial de comunicaciones o generar informes. Si tu token de acceso ha caducado o tu conexión está mal configurada, cualquier intento de obtener información de la línea de tiempo fallará silenciosamente o devolverá un error 401. Por ello, comprender cómo funciona la capa de autenticación es un requisito previo antes de realizar cualquier llamada de recuperación de datos.

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

---

Paso a paso

Paso 1. Establece tu conexión OAuth.

Antes de cualquier otra cosa, tu aplicación debe completar el flujo OAuth. La URL de autorización se construye usando tu clientid, redirecturi, los scopes configurados y los parámetros responsetype=code, accesstype=offline y prompt=consent. Una vez que el usuario aprueba, Zoho redirige de vuelta con un código de autorización. ^[7]

Paso 2. Intercambia el código de autorización por tokens.

Envía mediante POST el código de autorización al endpoint de tokens de Zoho usando granttype=authorizationcode junto con tu clientid, clientsecret y redirecturi. Una respuesta exitosa devuelve un accesstoken, un refreshtoken, un apidomain y un valor expires_in. Guarda todos estos datos, ya que los necesitarás en cada solicitud posterior. ^[7]

Paso 3. Persiste la conexión y registra la caducidad.

Guarda el accesstoken, el refreshtoken, el tokenexpiresat (calculado como el tiempo Unix actual más expiresin) y el apidomain en tu almacén de datos. La marca de tiempo de caducidad es fundamental: le indica a tu sistema cuándo debe renovarse el token antes de realizar llamadas a la API. ^[1]

Paso 4. Renueva el token antes de que caduque.

Al recuperar la conexión almacenada, comprueba si el tiempo actual está dentro de los 120 segundos anteriores a tokenexpiresat. Si es así, envía un POST al endpoint de tokens con granttype=refreshtoken, tu clientid, clientsecret y el refreshtoken almacenado. Si la operación es exitosa, actualiza el accesstoken y el tokenexpiresat almacenados con los nuevos valores. Este margen de 120 segundos reduce la posibilidad de que el token caduque durante una solicitud en curso. ^{[2] [3]}

Paso 5. Confirma que la conexión está activa antes de invocar cualquier herramienta.

Tras ejecutar la lógica de renovación, verifica que exista un objeto de conexión válido para el usuario. Si no se encuentra ninguna conexión —por ejemplo, porque el usuario nunca autorizó o porque la renovación falló— muestra un aviso de reconexión en lugar de continuar. Intentar invocar herramientas de Zoho sin un token activo resultará en una respuesta de error. ^[6]

Paso 6. Identifica la herramienta y el módulo correctos para recuperar la línea de tiempo.

Con una conexión válida disponible, determina qué herramienta de Zoho corresponde a los datos de la línea de tiempo para tu módulo objetivo (por ejemplo, Contactos, Prospectos o Negocios en Zoho CRM). El api_domain devuelto durante el intercambio de tokens es la URL base para todas las llamadas a la API; úsalo al construir tu ZohoCrmClient. Pasa el nombre de la herramienta y los parámetros requeridos (como module) a la capa de ejecución. ^[4]

Paso 7. Ejecuta la llamada a la herramienta.

Invoca la herramienta a través de tu capa de ejecución de API, proporcionando el nombre de la herramienta y un diccionario de parámetros. El sistema llamará a la API de Zoho usando el token de acceso actual y devolverá el payload de la línea de tiempo. Si el token ha rotado durante la sesión, el callback de renovación del token obtendrá automáticamente uno nuevo y reintentará la operación. ^{[4] [5]}

Paso 8. Gestiona la respuesta.

Una llamada exitosa devuelve los registros de la línea de tiempo como datos estructurados. Si la respuesta contiene una clave error, inspecciona el mensaje; las causas más comunes incluyen un token caducado que no se pudo renovar, un nombre de módulo no válido o scopes OAuth insuficientes. ^{[3] [4]}

---

Errores comunes

• refreshtoken ausente en intercambios posteriores. Zoho solo devuelve un refreshtoken en la primera autorización. Si lo pierdes, el usuario deberá volver a autorizar desde cero. Persístelo siempre de inmediato tras el intercambio inicial del código. ^[7]
• Caducidad del token no registrada correctamente. tokenexpiresat debe establecerse como int(time.time()) + int(expires_in) en el momento en que se recibe el token, no en el momento en que se almacena. Cualquier retraso entre la recepción y el almacenamiento provocará cálculos de caducidad prematuros. ^{[1] [3]}
• Uso incorrecto del apidomain. El apidomain en la respuesta del token puede variar según el centro de datos (p. ej., .com, .eu, .in). Usa siempre el dominio devuelto en el intercambio de tokens en lugar de codificar una URL de forma fija. ^[7]
• Inconsistencia en el campo de ID de organización. Al obtener información del usuario desde https://accounts.zoho.<DC>/oauth/user/info, el ID de organización puede aparecer bajo orgid, organizationid o ZGID según el centro de datos. Implementa lógica de respaldo para gestionar todas las variantes. ^[1]

---

Qué verificar

• El token es válido y no está dentro de los 120 segundos previos a su caducidad antes de emitir cualquier llamada de recuperación de la línea de tiempo; confirma que la lógica de renovación se ejecutó correctamente y que el nuevo access_token fue persistido. ^[2]
• El api_domain coincide con el centro de datos del usuario — verifica que el dominio almacenado durante el intercambio de tokens se esté usando como URL base para todas las solicitudes a la API de Zoho. ^{[4] [7]}
• Los scopes OAuth requeridos están incluidos — asegúrate de que los scopes configurados en tu URL de autorización cubran el acceso de lectura al módulo cuya línea de tiempo estás consultando. ^[7]