Cómo listar tickets por contacto en Zoho Desk

Listar todos los tickets de soporte asociados a un contacto específico en Zoho Desk es sencillo una vez que tienes el ID del contacto: una sola llamada a la API devuelve la lista completa de tickets de esa persona.

Por qué esto es importante

Cuando un cliente contacta repetidamente con tu equipo de soporte, necesitas una vista consolidada de cada ticket que haya abierto. Esto es esencial para entender el historial de un contacto antes de responder, para revisiones de escalación y para generar informes sobre contactos de alto volumen. Sin esta consulta, los agentes deben buscar o filtrar manualmente, lo cual es lento y propenso a errores.

Paso a paso

Paso 1. Identifica el contact_id de la persona cuyos tickets quieres recuperar. Puedes encontrarlo navegando a Contacts dentro de tu portal de Zoho Desk (el patrón de URL sigue desk.zoho.com/agent/{portal}/contacts) o consultando primero el endpoint de contactos. El ID es el identificador numérico único que aparece en la URL del registro del contacto. ^[1]

Paso 2. Confirma que tu token OAuth incluye los scopes correctos de Zoho Desk. Como mínimo necesitas Desk.tickets.READ y Desk.contacts.READ para resolver el contacto y leer sus tickets. Si estás usando una integración más amplia, scopes como Desk.tickets.ALL también cubrirán esta operación. ^[5]

Paso 3. Realiza una solicitud GET al siguiente endpoint de la API de Zoho Desk, sustituyendo el identificador real del contacto en la ruta: ^[2]

GET /api/v1/contacts/{contact_id}/tickets

La operación se identifica internamente como listticketsbycontact. El parámetro de ruta contactid es obligatorio; el parámetro de consulta opcional p puede usarse para controlar la paginación. ^[2]

Paso 4. En Python, la llamada tiene este aspecto: ^[2]

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

Pasa el ID del contacto como cadena de texto. Si necesitas una página específica de resultados, proporciona un diccionario de paginación como segundo argumento; de lo contrario, déjalo como None. ^[2]

Paso 5. Analiza la respuesta. La API de Zoho Desk devuelve registros de tickets con campos clave como asunto, estado, agente asignado y departamento. Nuestro equipo recomienda mostrar como mínimo: el asunto del ticket, el estado actual y el agente responsable, para que el interlocutor obtenga un resumen inmediatamente accionable. ^[6]

Paso 6. Si quieres un enlace directo en el navegador a cualquier ticket devuelto en la respuesta, el patrón de URL a construir es: ^[3]

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

Reemplaza {dc} con el sufijo de tu centro de datos (p. ej., com, eu, in), {portal} con el nombre de tu portal de Desk y {TicketId} con el ID obtenido de la respuesta de la API. ^[3]

---

*Beam Help es un recurso de soporte experto independiente, no el soporte oficial de Zoho.*

Errores comunes

• orgId ausente o incorrecto: Zoho Desk requiere que el ID de organización se envíe con cada solicitud a la API. Si está ausente, el sistema intentará descubrirlo automáticamente llamando primero al endpoint de organizaciones y luego persistirá el valor para llamadas futuras. Si ves errores de autenticación o de «org no encontrada», verifica que deskorgid esté correctamente almacenado y pasado al cliente. ^{[7] [8]}
• Scopes OAuth insuficientes: Solicitar tickets de un contacto requiere permisos de lectura tanto de contactos como de tickets. Si tu token fue emitido sin Desk.contacts.READ o Desk.tickets.READ, la API devolverá un error de permisos. Vuelve a autorizar con el conjunto completo de scopes. ^[5]
• Paginación no gestionada: El parámetro p controla qué página de resultados se devuelve. Si un contacto tiene muchos tickets y omites el manejo de la paginación, solo verás la primera página. Itera por las páginas hasta que la respuesta devuelva menos registros que el tamaño de página. ^[2]
• Centro de datos incorrecto: La URL base debe coincidir con el centro de datos donde está alojada tu cuenta de Desk. Usar desk.zoho.com para una cuenta alojada en la UE fallará; usa desk.zoho.eu en su lugar. ^[3]

Qué verificar

• Comprueba que el contact_id que estás pasando existe realmente en Zoho Desk abriendo el registro del contacto en el portal de agentes antes de realizar la llamada a la API. ^[1]
• Confirma que tu token OAuth activo incluye al menos Desk.tickets.READ y Desk.contacts.READ en su lista de scopes. ^[5]
• Verifica que el orgId (ID de organización) esté correctamente configurado en tu cliente de API, especialmente si esta es la primera llamada tras una nueva autorización OAuth. ^{[7] [8]}