Cómo eliminar un rol en Zoho Desk

Eliminar un rol en Zoho Desk se realiza mediante una única llamada autenticada a la API que identifica el rol por su identificador único. Aquí tienes todo lo que necesitas para hacerlo correctamente.

Por qué es importante

La gestión de roles es fundamental para controlar lo que tus agentes de Zoho Desk pueden ver y hacer. Con el tiempo, las organizaciones acumulan roles redundantes u obsoletos que saturan la configuración y confunden a los administradores. Saber cómo eliminarlos de forma programática — en lugar de buscarlos manualmente en la interfaz — ahorra tiempo y mantiene tu configuración ordenada, especialmente cuando se gestionan roles a gran escala mediante automatización o integraciones.

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

---

Paso a paso

Paso 1. Confirma que tienes los scopes de OAuth correctos.

Antes de realizar cualquier llamada a la API, verifica que tu token OAuth de Zoho Desk incluya los permisos necesarios. El scope requerido para operaciones a nivel de configuración (que incluye la gestión de roles) es Desk.settings.DELETE — junto con scopes relacionados como Desk.settings.READ y Desk.settings.ALL para un acceso más amplio. ^[3]

Paso 2. Obtén el role_id que deseas eliminar.

No puedes eliminar un rol sin conocer su identificador exacto. Utiliza una solicitud GET al endpoint de roles (o consulta el panel de administración de Zoho Desk) para listar los roles existentes y anota el role_id del que deseas eliminar. Guarda este valor — lo pasarás directamente en la llamada de eliminación.

Paso 3. Realiza la solicitud DELETE.

Envía una solicitud DELETE al siguiente endpoint, sustituyendo el identificador real del rol por {role_id}: ^[1]

DELETE /api/v1/roles/{role_id}

El nombre de la operación es deleterole, y acepta roleid como su parámetro de ruta principal, con un parámetro opcional p para opciones de consulta adicionales. ^[1]

Paso 4. Usa el helper del cliente Python (si corresponde).

Si estás trabajando con una integración basada en Python, la llamada se corresponde con un método de cliente sencillo. Pasa el role_id como cadena de texto y, opcionalmente, proporciona un diccionario para el parámetro p: ^[1]

def delete_role(self, role_id: str, p: dict = None):
    return self.c.request("DELETE", f"/api/v1/roles/{role_id}", p, None)

Paso 5. Inicializa el cliente de Desk con el org_id correcto.

Las llamadas a la API de Zoho Desk requieren que el ID de organización esté configurado en el cliente. Al construir la instancia de ZohoDeskClient, pasa el orgid junto con tu dominio de API y token de acceso. Si el orgid aún no está almacenado, el cliente puede descubrirlo automáticamente llamando al endpoint de organizaciones y guardando el primer resultado. ^[6]

Paso 6. Gestiona la renovación del token de forma proactiva.

Los tokens de acceso caducan. Envuelve tu llamada de eliminación dentro de un flujo que verifique la validez del token y lo renueve usando el refreshtoken almacenado antes de enviar la solicitud. Una función tokenrefresher debe obtener el último refresh token de tu almacén de datos, llamar al endpoint de renovación de OAuth y actualizar el access_token almacenado y la marca de tiempo de expiración. ^[6]

---

Errores comunes

• Endpoint de producto incorrecto. Zoho CRM también tiene un endpoint de eliminación de roles (DELETE /Contacts/roles/{roleid}), pero ese es para *roles de contacto de negocio* en CRM — no para roles de agentes de Desk. ^[2] Asegúrate de apuntar a /api/v1/roles/{roleid} y de usar un cliente autenticado en Desk, no un cliente de CRM. ^[1]

• orgid ausente o caducado. Zoho Desk requiere el ID de organización en cada solicitud. Si el orgid está vacío o desactualizado, la API rechazará la llamada. Verifica siempre que esté configurado antes de ejecutar la eliminación. ^[6]

• Scope de OAuth insuficiente. Si tu token fue generado sin Desk.settings.DELETE (o el más amplio Desk.settings.ALL), la API devolverá un error de autorización. Vuelve a generar tu token incluyendo el grupo de scopes de configuración completo. ^[3]

• Eliminar un rol que aún tiene agentes asignados. La API puede negarse a eliminar un rol que tenga agentes activos asociados. Reasigna o elimina esos agentes del rol antes de intentar la eliminación.

---

Qué verificar

• Cobertura de scopes: Confirma que tu token OAuth activo incluye Desk.settings.DELETE o Desk.settings.ALL antes de llamar al endpoint. ^[3]
• Endpoint y cliente correctos: Verifica que estás llamando a /api/v1/roles/{roleid} mediante una instancia de ZohoDeskClient — no un cliente de CRM — y que el orgid está configurado. ^[1][6]
• El rol ya no aparece: Tras un DELETE exitoso, realiza un GET en la lista de roles para confirmar que el rol ha sido eliminado y que ningún agente ha quedado inesperadamente sin asignación de rol.