Cómo listar los equipos de un agente en Zoho Desk

Recuperar los equipos asociados a un agente específico en Zoho Desk es sencillo mediante la API REST: una única solicitud GET devuelve la lista completa de equipos vinculados al ID de ese agente.

Por qué es importante

Al crear integraciones, automatizaciones o paneles de administración sobre Zoho Desk, a menudo necesitas saber a qué equipos pertenece un agente — por ejemplo, para enrutar tickets correctamente, auditar la membresía de equipos o sincronizar datos con un sistema externo. En lugar de navegar manualmente por la interfaz para cada agente, la API te permite recuperar esta información de forma programática y a escala. Como soporte experto independiente de Zoho (no soporte oficial de Zoho), Beam Help documenta este endpoint para que tus desarrolladores puedan ponerse en marcha rápidamente.

Paso a paso

Paso 1. Identifica el agent_id del agente cuyos equipos deseas listar. Este es el identificador único que Zoho Desk asigna a cada registro de agente. Puedes obtenerlo a partir de una llamada API previa que devuelva los detalles del agente, o desde el panel de administración de Zoho Desk. ^[6]

Paso 2. Construye la solicitud utilizando el siguiente patrón de endpoint:

GET /api/v1/agents/{agent_id}/teams

Reemplaza {agent_id} con el identificador numérico o de cadena real del agente que estás consultando. ^[6]

Paso 3. Opcionalmente, incluye el parámetro p en tu cadena de consulta para controlar la paginación si el agente pertenece a un gran número de equipos. Pásalo como un diccionario de pares clave-valor junto con tu solicitud. ^[6]

Paso 4. Envía la solicitud GET autenticada a la URL base de la API de Zoho Desk correspondiente a tu centro de datos, añadiendo la ruta indicada anteriormente. Una respuesta exitosa devolverá la lista de equipos asociados a ese agente. ^[6]

Paso 5. Si trabajas en Python, la llamada puede estructurarse como se muestra a continuación, donde agent_id es una cadena y p es un diccionario opcional de parámetros de consulta:

def list_associated_teams_of_agent(self, agent_id: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/agents/{agent_id}/teams", p, None)

Esto encapsula el endpoint en un método reutilizable en tu objeto cliente de la API. ^[6]

Errores comunes

• URL base del centro de datos incorrecta. Zoho Desk opera en múltiples centros de datos regionales (US, EU, IN, AU, etc.). Asegúrate de que la URL base que antepones a /api/v1/agents/{agent_id}/teams corresponda al centro de datos donde está alojada tu cuenta de Zoho Desk; de lo contrario, recibirás errores de autenticación o errores 404. ^[6]
• Token OAuth ausente o caducado. Todas las llamadas a la API de Zoho Desk requieren un token de acceso OAuth 2.0 válido en el encabezado Authorization. Si tu token ha caducado, la solicitud será rechazada antes de llegar al endpoint. ^[6]
• Formato de agent_id no válido. Pasar un ID de agente con formato incorrecto o inexistente generará una respuesta de error. Valida siempre el ID contra una lista de agentes conocidos antes de realizar la llamada. ^[6]

Qué verificar

• Confirma que el ID del agente es correcto cruzándolo con tu lista de agentes de Zoho Desk antes de llamar al endpoint.
• Verifica la paginación — si la respuesta parece incompleta, comprueba si existen páginas adicionales inspeccionando los metadatos de la respuesta y ajustando el parámetro p en consecuencia. ^[6]
• Revisa la membresía de equipos en la interfaz después de tu llamada a la API para confirmar que la lista de equipos devuelta coincide con lo configurado en los ajustes de administración de Zoho Desk, asegurándote de que los datos estén actualizados. ^[6]