Cómo actualizar registros en Zoho

Actualizar registros en Zoho requiere una conexión OAuth válida y activa con los permisos correctos — una vez configurados, el flujo de actualización gestiona la renovación del token automáticamente y escribe los cambios de vuelta en CRM o Desk.

Por qué esto es importante

Ya sea que estés sincronizando datos de contacto, cerrando tickets o modificando información de leads, las actualizaciones programáticas de registros dependen de un token OAuth activo y los permisos adecuados. Si tu token ha expirado o tus permisos son demasiado restrictivos, las llamadas de actualización fallarán silenciosamente o devolverán errores 401. Entender cómo funciona la capa de conexión te ayuda a diagnosticar y resolver estos problemas rápidamente.

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

---

Paso a paso

Paso 1. Confirma que tu conexión OAuth existe y tiene un token válido.

Antes de que cualquier actualización de registro pueda realizarse, el sistema debe encontrar una conexión almacenada para tu usuario. La conexión se busca en una tabla local zohoconnections usando tu userid. Si no se encuentra ninguna fila, el cliente de la API no puede inicializarse y todas las llamadas posteriores fallarán.^[3]

Paso 2. Permite que se ejecute el ciclo de renovación del token.

Los tokens se renuevan de forma proactiva cuando el tiempo actual está dentro de los 120 segundos del valor almacenado en tokenexpiresat. Una renovación exitosa escribe el nuevo accesstoken y el tokenexpiresat actualizado de vuelta en la fila de zohoconnections, de modo que la siguiente llamada siempre use una credencial actualizada.^[3] Si la renovación falla (por ejemplo, si el refresh_token falta o ha sido revocado), la función devuelve None y no se procesará ninguna actualización.^[1]

Paso 3. Verifica que los permisos OAuth correctos estén concedidos.

Para las actualizaciones de registros en Zoho CRM, tu concesión OAuth debe incluir ZohoCRM.modules.ALL o el permiso UPDATE equivalente a nivel de módulo. Para Zoho Desk, los permisos relevantes incluyen Desk.tickets.UPDATE, Desk.contacts.UPDATE, Desk.tasks.UPDATE y permisos UPDATE similares por objeto.^[5] Si estos permisos no se solicitaron durante la autorización OAuth original, deberás volver a autorizar e incluirlos explícitamente.

Paso 4. Inicializa el cliente de API correcto para tu producto.

Pasa apptype="crm" para apuntar a Zoho CRM, o apptype="desk" para apuntar a Zoho Desk. Para Desk, también se requiere un orgid — si aún no está almacenado, el sistema llamará a getallorganizations para descubrirlo y guardarlo automáticamente.^[1] Para CRM, se construye un ZohoCrmClient usando el apidomain y el access_token almacenados, con el callback de renovación del token conectado.^[4]

Paso 5. Ejecuta la herramienta de actualización con el ID del registro objetivo y los campos modificados.

Una vez que el cliente de API esté listo, llama a execute_tool con el nombre de la herramienta de actualización correspondiente y un objeto params que incluya el id del registro y los campos que deseas cambiar. La capa de ejecución intentará la llamada y, si se devuelve una pregunta de aclaración o un error en el resultado, ese mensaje se muestra directamente para que puedas corregir el payload y volver a intentarlo.^[8]

Paso 6. Confirma que los metadatos de la conexión están actualizados tras un callback de autenticación.

Si recientemente volviste a autorizar, verifica que el callback de autenticación haya escrito correctamente el accesstoken, refreshtoken, apidomain y tokenexpiresat más recientes en zohoconnections. El callback realiza un upsert — actualizando la fila existente si se encuentra una, o insertando una nueva en caso contrario — y también almacena crmorgid para la tenencia de CRM.^[2]

---

Errores comunes

• orgid faltante en llamadas a Desk. Si deskorg_id está vacío o contiene solo espacios en blanco, el cliente se construye de todas formas, pero la primera llamada a la API activa una búsqueda de autodescubrimiento. Si esa búsqueda también falla (por ejemplo, debido a un permiso faltante en Desk.basic.READ), todas las actualizaciones posteriores de Desk generarán errores.^[1]
• La renovación del token no devuelve ningún accesstoken. Si ZohoOAuth.refreshtokens responde sin una clave access_token, el renovador devuelve None y el token obsoleto permanece en uso, causando errores 401 en las llamadas de actualización.^[1][3]
• Permisos faltantes de la concesión original. Los permisos se establecen en el momento de la autorización. Agregar permisos UPDATE a tu archivo de configuración no actualiza retroactivamente una concesión existente — el usuario debe completar un nuevo flujo OAuth.^[5]
• Bloqueo de SQLite durante actualizaciones concurrentes. Las operaciones de relleno o migración que actualizan zoho_connections deben usar una única conexión/transacción para evitar conflictos de bloqueo.^[6]

---

Qué verificar

• Confirma que la fila de zohoconnections para tu userid tiene un refreshtoken no nulo y que tokenexpires_at es una marca de tiempo Unix válida.^[3]
• Verifica que tu concesión OAuth incluya el permiso UPDATE relevante para el módulo que estás apuntando (por ejemplo, ZohoCRM.modules.ALL para CRM, Desk.tickets.UPDATE para tickets de Desk).^[5]
• Después de cualquier nueva autorización, comprueba que el apidomain almacenado en zohoconnections contenga zohoapis. para que el centro de datos se infiera correctamente en las llamadas API posteriores.^[2]