Cómo recuperar acciones en Zoho

Recuperar acciones en Zoho implica iterar sobre la lista de acciones de un plan estructurado y ejecutar cada llamada a herramienta en secuencia, mientras el sistema gestiona automáticamente los permisos de solo lectura frente a los de escritura.

Por qué esto es importante

Cuando construyes automatizaciones o flujos de trabajo asistidos por IA sobre Zoho, tu integración necesita obtener y ejecutar de forma fiable la secuencia correcta de acciones desde un objeto de plan. Comprender cómo funciona el proceso de recuperación y ejecución te ayuda a depurar pasos fallidos, gestionar preguntas de aclaración con elegancia y asegurarte de que las credenciales de conexión son válidas antes de que se invoque cualquier herramienta.

Paso a paso

Paso 1. Confirma que tu conexión con Zoho está activa antes de intentar recuperar o ejecutar acciones. El sistema llama a getzohoapi con tu userid y apptype para obtener un identificador de API activo y los metadatos de conexión. Si no se devuelve una conexión válida, el proceso se detiene de inmediato y muestra un error de reconexión al llamante. ^[2]

Paso 2. Analiza el objeto de plan para acceder a su lista actions. El plan se almacena como JSON (comúnmente denominado plan_json), y recuperas la lista con plan.get("actions"). Si el JSON está mal formado o la lista está ausente, el sistema registra el fallo y devuelve un error "Invalid plan" — por lo tanto, valida siempre el payload del plan antes de continuar. ^[4]

Paso 3. Itera sobre cada acción de la lista. Cada entrada de acción contiene como mínimo una clave tool (el nombre de la herramienta de Zoho a invocar) y un diccionario params con los argumentos para esa herramienta. Recorre la lista y extrae ambos valores en cada paso. ^[1]

Paso 4. Valida cada llamada a herramienta antes de ejecutarla. Para cada acción, llama a validatetoolcall con el apptype, el nombre de la herramienta y sus params. Esto devuelve un nivel de permiso — ya sea "read" u otro valor. Si todas las acciones del plan resuelven al permiso "read", el plan completo se clasifica como de solo lectura y puede ejecutarse de inmediato sin un paso de aprobación separado. Si alguna acción no tiene permiso "read", el indicador allread_only se establece en False y el plan requiere confirmación explícita del usuario antes de aplicarse. ^[5]

Paso 5. Ejecuta cada acción usando executetoolwithrepair. Pasa el identificador api, apptype, el nombre de la tool y los params. Para herramientas de solo lectura, establece allowrepair=True para que el sistema pueda reintentar automáticamente con parámetros corregidos si el primer intento falla. La función devuelve un diccionario execout que contiene el result y, opcionalmente, una clarifyingquestion si la herramienta necesita más información del usuario. ^[3]

Paso 6. Comprueba la salida de cada ejecución. Si execout.get("clarifyingquestion") tiene valor, pausa el bucle de acciones, muestra la pregunta al usuario y regístrala en tu almacén de mensajes de chat antes de liberar cualquier bloqueo de concurrencia. Si el resultado es un diccionario que contiene una clave "error", captura ese mensaje de error para mostrarlo. De lo contrario, considera la acción como completada con éxito. ^[2]

Paso 7. Tras una ejecución exitosa, construye enlaces contextuales a los registros afectados usando buildzoholinks. Proporciona el result, el nombre de herramienta resuelto (execout.get("tool") or tool), los params resueltos, apptype, el código del centro de datos (dc) y cualquier identificador de organización/portal de los metadatos de conexión (crmorgid, deskorgid, desk_portal). Estos enlaces permiten a los usuarios navegar directamente a los registros que fueron leídos o modificados. ^[8]

Paso 8. Para herramientas basadas en navegador (como browsernavigateandscreenshot para inspeccionar páginas de administración de Zoho), el proceso de ejecución es ligeramente diferente. Primero se comprueba el BROWSERTOOLREGISTRY para confirmar que la herramienta existe, luego se validan los params requeridos y, finalmente, se verifica el estado de autenticación de la sesión del navegador. Si la sesión ha expirado, el sistema devuelve un campo actionrequired que te indica que debes volver a autenticarte a través del endpoint de inicio de sesión del navegador. ^[7]

Errores comunes

• Conexión con Zoho ausente: Si getzohoapi no devuelve nada, no se ejecutará ninguna acción. Verifica siempre que la conexión esté establecida y que el app_type correcto esté especificado antes de activar un plan. ^[4]
• JSON de plan no válido: Una cadena plan_json mal formada provoca que toda la operación de aplicación se cancele. El sistema registra una muestra del payload incorrecto (hasta 200 caracteres) para facilitar la depuración. ^[4]
• Superar el límite de acciones: El sistema comprueba planactioncount frente a Config.MAXPLANACTIONS cuando el indicador de aplicación del motor de flujo de trabajo está activo. Los planes con demasiadas acciones pueden ser rechazados antes de que se invoque cualquier herramienta. ^[4]
• Expiración de la sesión del navegador: Para llamadas a herramientas basadas en navegador, una sesión expirada o no autenticada devuelve un error en lugar de fallar silenciosamente — presta atención a la clave "action_required" en la respuesta. ^[7]
• Acciones no de solo lectura en modo streaming: En el endpoint de plan en streaming, los planes de solo lectura se ejecutan en línea con un feed de estado en tiempo real. Los planes que contienen acciones de escritura se devuelven al cliente como un payload de plan pendiente, lo que requiere un paso de aplicación separado. ^[5]

Qué verificar

• Confirma que getzohoapi devuelve un identificador de API válido y que el valor dc (centro de datos) en los metadatos de conexión coincide con la región de tu cuenta de Zoho.
• Verifica que la clave tool de cada acción coincida con un nombre de herramienta registrado y que todos los params REQUIRED estén presentes antes de enviar el plan.
• Tras la ejecución, inspecciona el campo status en cada resultado — busca "success" frente a "error" — y confirma que buildzoholinks devuelve URLs de registros navegables para cualquier dato afectado. ^[3][8]

---

*Beam Help ofrece soporte experto independiente para Zoho y no es el soporte oficial de Zoho. Prueba siempre la ejecución de planes en un entorno de pruebas antes de aplicar cambios a los datos de producción.*