Beam Help
Solicitar ayuda

How-to · Zoho DESK

Cómo listar los equipos asociables en Zoho Desk

Recupera los equipos que pueden asociarse con tickets o cuentas.

Listar los equipos asociables en Zoho Desk es sencillo una vez que sabes qué endpoint de la API debes llamar y cómo pasar los parámetros correctos. Este artículo te guía a través del proceso utilizando la API REST de Zoho Desk.


Por qué esto es importante


Cuando construyes integraciones o automatizaciones sobre Zoho Desk, a menudo necesitas saber qué equipos pueden asociarse con un recurso determinado — por ejemplo, al enrutar tickets o asignar agentes. El endpoint de "equipos asociables" te proporciona una lista filtrada de equipos elegibles para la asociación, lo cual es distinto de simplemente listar todos los equipos de cada departamento. Comprender la diferencia te ayuda a evitar asignar tickets a equipos que no son elegibles y mantiene tus flujos de trabajo ordenados.


Paso a paso


Paso 1. Confirma que tus scopes de OAuth están configurados correctamente antes de realizar cualquier llamada a la API. Tu integración con Zoho Desk necesita como mínimo Desk.basic.READ en su lista de scopes para leer datos de equipos y agentes. Revisa tu configuración de OAuth y asegúrate de que este scope — junto con cualquier otro que tu aplicación requiera — esté presente. [5]


Paso 2. Realiza una solicitud GET al endpoint /api/v1/teams/associable. Esta es la operación dedicada para recuperar los equipos que pueden asociarse, y acepta un diccionario de parámetros de consulta opcionales (comúnmente denominado p) para filtrar o paginar. [1]


GET /api/v1/teams/associable

En Python, la llamada tiene este aspecto:


result = desk_client.list_associable_teams(p={"limit": 20})

El argumento p es opcional — omítelo por completo si deseas la respuesta predeterminada sin filtros adicionales aplicados. [1]


Paso 3. Si necesitas una visión más amplia — todos los equipos de cada departamento con el que está asociada tu cuenta — utiliza en su lugar el endpoint separado GET /api/v1/teams. Esta operación, listteamsfromallassociated, devuelve equipos de todos los departamentos vinculados en lugar de solo aquellos elegibles para la asociación. [3]


GET /api/v1/teams

result = desk_client.list_teams_from_all_associated(p=None)

Usa este endpoint cuando quieras un inventario completo de equipos, y el endpoint de asociables cuando necesites restringir los resultados a equipos que son destinos válidos para una acción de asociación. [3]


Paso 4. Si tu caso de uso es específico de un agente — por ejemplo, quieres saber a qué equipos pertenece ya un agente en particular — existe un tercer endpoint con alcance a un agente individual. Envía una solicitud GET a /api/v1/agents/{agentid}/teams, reemplazando {agentid} con el identificador numérico o de cadena del agente en cuestión. [8]


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

result = desk_client.list_associated_teams_of_agent(agent_id="98765", p=None)

Esto es útil para auditar la pertenencia a equipos o para rellenar previamente menús desplegables de la interfaz filtrados al contexto de un agente específico. [8]


Paso 5. Analiza la respuesta. Los tres endpoints devuelven sus datos a través del mismo mecanismo de solicitud subyacente, por lo que la estructura de la respuesta seguirá el sobre estándar de la API de Zoho Desk. Itera sobre la colección devuelta para extraer los IDs de los equipos, los nombres y cualquier otro atributo que necesite tu integración. [1][3][8]


Errores comunes


  • Scope Desk.basic.READ ausente. Esta es la razón más común por la que estos endpoints devuelven un 401 o 403. Verifica que Desk.basic.READ (y Desk.basic.CREATE si planeas escribir) esté incluido en tu cadena de scopes de OAuth. Un scope faltante bloqueará silenciosamente el acceso a los datos de agentes y equipos incluso si los scopes relacionados con tickets están presentes. [5]

  • Confundir "asociables" con "todos los equipos". El endpoint /api/v1/teams/associable es intencionalmente más restrictivo que /api/v1/teams. Si llamas al incorrecto, es posible que veas muy pocos equipos (y pierdas opciones válidas) o demasiados (y permitas asociaciones no válidas). Ajusta el endpoint a tu caso de uso real. [1][3]

  • Olvidar el orgid. Zoho Desk es compatible con múltiples organizaciones. Si tu conexión aún no ha resuelto el deskorg_id correcto, las llamadas a la API pueden devolver datos de la organización incorrecta o fallar por completo. Asegúrate de que el ID de organización se descubra y almacene antes de realizar solicitudes relacionadas con equipos. [4]

Qué verificar


  • Verifica que Desk.basic.READ aparezca en tu configuración activa de scopes de OAuth y que el token haya sido reemitido tras cualquier cambio de scope. [5]
  • Confirma que la respuesta de /api/v1/teams/associable devuelve una lista no vacía; si está vacía, comprueba que tu cuenta tenga equipos configurados en Zoho Desk y que se esté utilizando el org_id correcto. [1][4]
  • Si estás filtrando por agente, valida que el agentid que pasas a /api/v1/agents/{agentid}/teams sea un identificador de agente válido y activo en tu organización de Desk. [8]

---


*Beam Help ofrece soporte experto independiente para los productos de Zoho y no es el soporte oficial de Zoho. Consulta siempre la documentación propia de Zoho para conocer los últimos cambios en la API.*

Sources cited

  1. [1] GET /api/v1/teams/associable
  2. [2] server.py: build_zoho_links
  3. [3] GET /api/v1/teams
  4. [4] server.py: get_zoho_api
  5. [5] config.py
  6. [6] server.py: chat
  7. [7] GET /api/v1/agents/{agent_id}/teams
Listar Equipos Asociables en Zoho Desk | Beam Help — Beam Help