Cómo recuperar la configuración de automatización en Zoho

La recuperación de la configuración de automatización en Zoho CRM se realiza mediante una única solicitud GET autenticada al endpoint /settings/automation, con filtrado opcional por módulo. Aquí está todo lo que nuestro equipo en Beam Help — soporte experto independiente para Zoho, no soporte oficial de Zoho — ha documentado sobre cómo realizar esa llamada de forma fiable.

Por qué esto es importante

Cuando necesitas auditar, replicar o solucionar problemas con reglas de flujo de trabajo y lógica de automatización dentro de Zoho CRM, necesitas una forma programática de obtener la configuración actual. El endpoint /settings/automation te proporciona exactamente eso, devolviendo la configuración de automatización de tu organización — o de un módulo específico si acota la consulta. Esto es especialmente útil al crear herramientas de administración, ejecutar comprobaciones de cumplimiento o migrar configuraciones entre entornos.

Paso a paso

Paso 1. Asegúrate de que existe una conexión OAuth válida.

Antes de que cualquier llamada a la API pueda tener éxito, tu integración debe disponer de un token de acceso activo para el usuario de destino. El registro de conexión se busca en tu almacén local mediante user_id, y si el token está a menos de 120 segundos de expirar, se renueva automáticamente antes de que salga la solicitud — esta ventana de renovación proactiva está diseñada para evitar errores 401 a mitad de la solicitud. ^[5]

Paso 2. Obtén una instancia del cliente de la API de Zoho CRM.

Llama a getzohoapi(userid, apptype="crm") para recibir un objeto API completamente inicializado. Internamente, esta función recupera la conexión almacenada, configura un callback tokenrefresher que vuelve a obtener un accesstoken actualizado desde el endpoint de tokens de Zoho cuando es necesario, y devuelve una instancia de ZohoCrmApi lista para realizar llamadas. ^[1]

El tokenrefresher funciona leyendo el último refreshtoken de la base de datos, enviándolo al endpoint de tokens de Zoho junto con tu clientid y clientsecret, y guardando el nuevo accesstoken y tokenexpiresat de vuelta en la tabla zohoconnections. ^{[1] [2]}

Paso 3. Llama al endpoint de configuración de automatización.

Con tu objeto API en mano, invoca el método get_automation:

result = api.get_automation()          # all modules
result = api.get_automation(m="Leads") # scoped to a specific module

Internamente, esto emite una solicitud GET a /settings/automation, añadiendo {"module": m} como parámetro de consulta solo cuando se proporciona un nombre de módulo. ^[3]

El identificador de la operación es get_automation y el método HTTP es GET /settings/automation. ^[3]

Paso 4. Gestiona la respuesta.

El método devuelve lo que la API REST de Zoho CRM envía de vuelta — normalmente un objeto JSON que contiene tus reglas de automatización. Comprueba las claves de nivel superior en busca de indicadores de error antes de procesar. Si el token había expirado silenciosamente, el callback token_refresher se activa automáticamente y el cliente reintenta la solicitud, por lo que los fallos de autenticación transitorios se gestionan sin código adicional de tu parte. ^{[1] [5]}

Paso 5. (Opcional) Limita el alcance por módulo.

Pasa el nombre del módulo de CRM como argumento m — por ejemplo "Leads", "Contacts" o "Deals" — para limitar la respuesta únicamente a las reglas de automatización pertenecientes a ese módulo. Si omites el argumento, se devuelve la configuración de todos los módulos. ^[3]

Errores comunes

• Registro de conexión ausente o expirado. Si getzohoconnection devuelve None porque no existe ninguna fila en zohoconnections para el userid indicado, getzohoapi también devolverá None y cualquier llamada a la API posterior fallará con un error de atributo. Verifica siempre que el flujo OAuth se completó correctamente y que se guardó una fila de conexión antes de intentar recuperar la configuración. ^{[1] [5]}

• apptype incorrecto. El endpoint de configuración de automatización pertenece a Zoho CRM, por lo que apptype debe ser "crm". Pasar "desk" redirige el cliente a ZohoDeskApi, que apunta a un conjunto de endpoints completamente diferente y no expondrá la configuración de automatización de CRM. ^[1]

• Bucle de renovación de token con un refreshtoken inválido. Si ZohoOAuth.refreshtokens devuelve un payload sin la clave access_token — por ejemplo, cuando el refresh token ha sido revocado — el renovador devuelve None y la llamada fallará. La solución es volver a ejecutar el flujo de autorización OAuth para obtener un nuevo par de tokens. ^{[2] [5]}

• Puerto incorrecto durante el OAuth inicial. El URI de redirección de OAuth está registrado para http://localhost:8080/api/authcallback. Ejecutar el servidor en cualquier otro puerto hará que el callback de autorización falle, lo que significa que nunca se almacenarán tokens y cada llamada a la API posterior — incluida getautomation — no tendrá nada con lo que trabajar. ^[4]

Qué verificar

• Confirma que hay un token válido almacenado — consulta zohoconnections para el userid de destino y verifica que tokenexpiresat está en el futuro, o que la ruta de renovación es funcional.
• Verifica la estructura de la respuesta del endpoint — asegúrate de que el JSON devuelto contiene las claves de reglas de automatización esperadas y no es un objeto de error (p. ej. {"code": "INVALID_TOKEN", ...}).
• Confirma la ortografía del nombre del módulo — si pasaste el parámetro m, comprueba el nombre de la API del módulo (distingue mayúsculas de minúsculas) con tu lista de módulos de Zoho CRM para evitar una respuesta vacía o errónea. ^[3]