Cómo recuperar reglas de asignación en Zoho

La recuperación de reglas de asignación en Zoho CRM se realiza mediante una única solicitud GET autenticada al endpoint /settings/assignment_rules, pasando el módulo de destino como parámetro.

Por qué esto es importante

Las reglas de asignación controlan cómo los registros entrantes — leads, contactos, negocios y más — se distribuyen automáticamente a tu equipo de ventas. Si estás creando una integración, auditando la configuración de tu CRM o sincronizando reglas con un sistema externo, necesitarás obtener estas reglas mediante programación. Esto también es útil para diagnosticar por qué los registros no se están enrutando como se esperaba. Como recordatorio, Beam Help es soporte experto independiente para Zoho y no es el soporte oficial de Zoho.

---

Paso a paso

Paso 1. Registra tu aplicación y obtén credenciales OAuth visitando la Zoho API Console, creando una aplicación basada en servidor y anotando tu Client ID y Client Secret. Configura tu URI de redirección (por ejemplo, http://localhost:8080/api/auth_callback) y asegúrate de incluir el scope ZohoCRM.settings.ALL entre los scopes seleccionados. ^[8]

Paso 2. Genera una URL de autorización OAuth construyendo una solicitud con los parámetros clientid, redirecturi, scope, responsetype y accesstype. El parámetro access_type debe establecerse en offline y prompt en consent para que se emita un refresh token junto con el access token. ^[2]

Paso 3. Intercambia el código de autorización devuelto por Zoho por un access token y un refresh token. Envía una solicitud POST al endpoint de tokens de Zoho con granttype: authorizationcode, tu clientid, clientsecret, redirecturi y el valor code. Almacena de forma segura los valores resultantes accesstoken, refreshtoken, apidomain y tokenexpiresat para su uso posterior. ^[2]

Paso 4. Cuando tu access token expire, usa el refresh token almacenado para obtener uno nuevo. Envía una solicitud POST con granttype: refreshtoken junto con tu clientid y clientsecret. Actualiza los valores almacenados de accesstoken y tokenexpires_at después de cada actualización exitosa para que las llamadas posteriores permanezcan autenticadas. ^[3]

Paso 5. Con un access token válido disponible, llama al endpoint de reglas de asignación. Emite una solicitud GET a:

GET /settings/assignment_rules?module=<ModuleName>

El parámetro module (denominado m en la implementación subyacente) especifica de qué módulo de Zoho CRM deseas recuperar las reglas de asignación — por ejemplo, Leads, Contacts o Deals. ^[1]

En Python, esta llamada tiene el siguiente aspecto:

def get_assignment_rules(self, m: str):
    return self.c.request("GET", "/settings/assignment_rules", {"module": m})

El objeto cliente (self.c) debe tener ya un access token válido y actualizado antes de realizar esta llamada. ^[1]

Paso 6. Gestiona la respuesta. Una llamada exitosa devuelve las reglas de asignación configuradas para el módulo especificado. Si el token ha expirado o el scope es insuficiente, recibirás un error de autenticación — en ese caso, activa el flujo de actualización de token descrito en el Paso 4 y vuelve a intentarlo. ^[3]

---

Errores comunes

• Scope faltante. Si ZohoCRM.settings.ALL no está incluido en la configuración de tu scope OAuth, la API rechazará la solicitud. Verifica los scopes registrados en la Zoho API Console y en la configuración de tu entorno. ^[8]

• Access token expirado. Los access tokens de Zoho tienen una vida útil limitada (normalmente 3600 segundos). Si tokenexpiresat ha pasado y no has actualizado el token, la llamada fallará. Comprueba siempre la expiración antes de realizar una solicitud y actualiza de forma proactiva. [^2, ^3]

• Centro de datos incorrecto. Zoho opera en múltiples centros de datos (com, eu, in, com.au, jp). El valor api_domain devuelto durante el intercambio de tokens debe usarse como URL base para todas las llamadas a la API — no uses https://www.zohoapis.com de forma fija si tu organización está en un DC diferente. [^5, ^8]

• Sensibilidad a mayúsculas en el nombre del módulo. El parámetro module debe coincidir exactamente con el nombre de API interno del módulo en Zoho CRM. Usa el nombre de API (p. ej., Leads, no leads) para evitar un error de «módulo no encontrado». ^[1]

---

Qué verificar

• El scope está presente: Confirma que ZohoCRM.settings.ALL aparece en tus scopes OAuth registrados y en la configuración de tu .env antes de realizar la llamada. ^[8]
• El token está actualizado: Verifica que el valor almacenado de tokenexpiresat sea una fecha futura; si no lo es, ejecuta el flujo de actualización antes de llamar al endpoint. ^[3]
• URL base correcta: Asegúrate de usar el valor api_domain devuelto durante el intercambio de tokens como raíz de tus solicitudes a la API, no un dominio fijo. ^[5]