Cómo listar tickets por cuenta en Zoho Desk

Listar los tickets asociados a una cuenta específica en Zoho Desk es sencillo una vez que tienes el ID de cuenta correcto y los scopes de API adecuados configurados. Esta guía recorre el endpoint exacto y los pasos de configuración que utiliza nuestro equipo.

Por qué esto es importante

Al gestionar el soporte empresarial, a menudo necesitas ver todos los tickets abiertos o históricos vinculados a una sola empresa, en lugar de a un contacto individual. Obtener los tickets por cuenta ofrece a los responsables de soporte una vista consolidada del historial completo de soporte de una organización cliente, lo que agiliza considerablemente las decisiones de escalado y las revisiones de SLA.

Paso a paso

Paso 1. Confirma que tus scopes de OAuth incluyen acceso a tickets y cuentas de Desk.

Antes de realizar cualquier llamada a la API, verifica que tu token OAuth de Zoho Desk conectado tenga concedidos como mínimo los scopes Desk.tickets.READ y Desk.contacts.READ. Sin estos, la solicitud será rechazada en la capa de autorización. Nuestro equipo recomienda incluir también Desk.tickets.ALL para que las operaciones de escritura estén disponibles si se necesitan más adelante. ^[2]

Paso 2. Identifica el ID de cuenta que deseas consultar.

Navega a tu portal de Zoho Desk y abre la sección Cuentas. Abre el registro de la cuenta específica y copia el ID numérico desde la URL o el panel de detalles del registro. Este es el valor account_id que pasarás al endpoint. Si trabajas de forma programática, también puedes recuperarlo navegando a la lista de cuentas en la ruta /accounts de tu portal. ^[1]

Paso 3. Llama al endpoint de listado de tickets por cuenta.

Envía una solicitud GET a la siguiente ruta, sustituyendo tu ID de cuenta real:

GET /api/v1/accounts/{account_id}/tickets

La operación se denomina listticketsby_account. Acepta dos parámetros:

• account_id — el ID numérico de la cuenta (obligatorio, parte de la ruta URL)
• p — un diccionario opcional de parámetros de consulta adicionales, como paginación o filtros

Una llamada mínima en Python tiene este aspecto:

def list_tickets_by_account(self, account_id: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/accounts/{account_id}/tickets", p, None)

^[3]

Paso 4. Asegúrate de que tu cliente de Desk tiene un orgId válido configurado.

Zoho Desk requiere un ID de organización (orgId) en cada solicitud a la API. Si tu integración aún no ha almacenado este valor, el cliente puede descubrirlo automáticamente llamando al endpoint de organizaciones en el primer uso. El ID descubierto se persiste para que las llamadas posteriores —incluida listticketsby_account— lleven el encabezado correcto de forma automática. ^[5][8]

Paso 5. Analiza y muestra la lista de tickets devuelta.

La respuesta será un objeto JSON que contiene los registros de tickets de esa cuenta. Los campos clave que debes mostrar a los usuarios finales incluyen el asunto del ticket, el estado, el agente asignado y la fecha de creación. Omite los campos de ID internos en cualquier visualización orientada al usuario para mantener la salida legible. ^[6]

Paso 6. Construye un enlace directo al portal para cada ticket (opcional).

Si deseas proporcionar a los agentes un enlace en el que puedan hacer clic para acceder a cada ticket, construye la URL utilizando el siguiente patrón:

https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}

Reemplaza {dc} con el sufijo de tu centro de datos (p. ej., com, eu), {portal} con el nombre de tu portal o el ID de organización, y {TicketId} con el ID de la respuesta de la API. ^[4]

---

Errores comunes

• Encabezado orgId ausente. Si el cliente de Desk se inicializa sin un ID de organización, todas las solicitudes —incluidas las consultas de tickets por cuenta— fallarán. Asegúrate de que el flujo de autodescubrimiento se haya ejecutado al menos una vez y de que el ID se haya persistido. ^[5][8]
• Scopes insuficientes. Para solicitar tickets se requiere como mínimo Desk.tickets.READ. Si tu token fue emitido únicamente con Desk.basic.READ, el endpoint devolverá un error de autorización. Vuelve a autorizar con el conjunto completo de scopes. ^[2]
• Centro de datos incorrecto. La URL base debe coincidir con el centro de datos donde está alojado tu portal de Zoho Desk. Usar desk.zoho.com para un portal alojado en la UE fallará; utiliza desk.zoho.eu en su lugar. ^[4]

---

Qué verificar

• Confirma que el account_id en tu solicitud coincide con una cuenta existente en Zoho Desk — un ID incorrecto devolverá un resultado vacío o un error 404 en lugar de un mensaje que indique claramente el problema.
• Verifica que el token OAuth en uso tenga los scopes Desk.tickets.READ y Desk.contacts.READ antes de pasar a producción. ^[2]
• Tras la primera llamada exitosa, comprueba que el deskorgid se haya almacenado en tu registro de conexión para que las solicitudes futuras no necesiten redescubrirlo. ^[8]

---

*Beam Help es un recurso de soporte experto independiente para productos Zoho y no es el soporte oficial de Zoho. Para problemas a nivel de plataforma, abre siempre un ticket directamente con Zoho.*