Cómo listar los archivos adjuntos de un ticket en Zoho Desk

Listar todos los adjuntos de un ticket en Zoho Desk es sencillo una vez que conoces el endpoint correcto de la API y tienes los scopes de OAuth adecuados configurados. Este artículo te guía paso a paso por la llamada exacta y la configuración necesaria — de parte de Beam Help, tu soporte experto independiente para Zoho (no es soporte oficial de Zoho).

Por qué esto es importante

Cuando construyes integraciones, automatizaciones o flujos de trabajo de auditoría, a menudo necesitas recuperar mediante programación todos los archivos adjuntos a un ticket de soporte. Ya sea que estés sincronizando adjuntos con un almacén de documentos externo, validando que se subieron los archivos requeridos, o simplemente mostrándolos en un portal personalizado, saber cómo llamar correctamente al endpoint de listado de adjuntos ahorra un tiempo considerable de depuración.

Paso a paso

Paso 1. Confirma tus scopes de OAuth.

Antes de realizar cualquier llamada a la API, asegúrate de que tu aplicación conectada tenga concedidos los permisos necesarios a nivel de ticket. Como mínimo, tu token de OAuth debe incluir Desk.tickets.READ — e idealmente Desk.tickets.ALL — para recuperar datos del ticket, incluidos los adjuntos. ^[8]

Paso 2. Identifica el ID del ticket.

Necesitas el ticketId (o ticket_id) único del ticket cuyos adjuntos deseas listar. Este es el identificador interno de Zoho Desk, no el número de ticket legible que se muestra en la interfaz. Puedes obtenerlo a partir de una búsqueda previa de tickets o de la respuesta de creación. ^[2]

Paso 3. Envía una solicitud GET al endpoint de adjuntos.

Realiza un GET HTTP a la siguiente ruta, sustituyendo el identificador real de tu ticket:

GET /api/v1/tickets/{ticketId}/attachments

Esta operación — denominada listticketattachments — devuelve la colección de archivos asociados a ese ticket. ^[2] Una operación equivalente llamada list_attachments utiliza el mismo método HTTP y la misma estructura de ruta, lo que confirma que esta es la ruta canónica. ^[3]

En Python, usando un wrapper de cliente preconfigurado, la llamada tiene este aspecto:

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

El parámetro opcional p puede contener argumentos de cadena de consulta, como controles de paginación. ^[2]

Paso 4. Gestiona la paginación si es necesario.

El endpoint acepta un parámetro p para la paginación. Si un ticket tiene muchos adjuntos, pasa los valores de página u offset adecuados en ese diccionario para recuperar páginas de resultados adicionales. [^2, ^3]

Paso 5. Accede a un adjunto individual (opcional).

Si necesitas los metadatos completos de un archivo específico después de listarlos, utiliza el endpoint de adjunto individual añadiendo el attachmentId a la ruta:

GET /api/v1/tickets/{ticketId}/attachments/{attachmentId}

Esta operación getticketattachment devuelve información detallada sobre ese archivo en particular. ^[5]

Paso 6. Recupera adjuntos en un borrador de transición (avanzado, opcional).

Si tu flujo de trabajo utiliza transiciones de tickets y necesitas adjuntos asociados a un borrador de transición específico en lugar del ticket en sí, existe un endpoint separado:

GET /api/v1/tickets/{ticketId}/transitions/{transitionId}/attachments

Esta es una operación distinta y solo debe usarse cuando necesites específicamente datos de adjuntos a nivel de transición. ^[7]

Errores comunes

• Scope de OAuth ausente o insuficiente. Si tu token solo tiene Desk.tickets.WRITE o Desk.tickets.CREATE pero no Desk.tickets.READ ni Desk.tickets.ALL, la API rechazará la solicitud. Verifica siempre la lista completa de scopes en tu configuración de OAuth. ^[8]

• Confundir el número de ticket con el ID del ticket. El ticketId en la ruta de la URL es el identificador interno generado por el sistema. Usar el número de ticket visible (p. ej., "TKT-1042") resultará en un error 404 o de registro inválido. Obtén el ID correcto a partir de una respuesta previa de la API.

• Olvidar añadir adjuntos antes de listarlos. Si estás haciendo pruebas y la lista devuelve un resultado vacío, confirma que los archivos hayan sido subidos realmente. Los adjuntos se añaden mediante un POST a la misma ruta /api/v1/tickets/{ticketId}/attachments. [^4, ^6]

• Adjuntos de transición vs. adjuntos del ticket. El endpoint de borrador de transición (/transitions/{transitionId}/attachments) no es intercambiable con el endpoint principal de adjuntos del ticket. Llamar al incorrecto devolverá un conjunto de resultados vacío o no relacionado. ^[7]

Qué verificar

• Verificación del scope: Confirma que Desk.tickets.READ o Desk.tickets.ALL aparece en la lista de scopes de tu token de OAuth activo antes de realizar la llamada. ^[8]
• ID de ticket correcto: Valida que el ticketId que estás pasando es el ID interno del sistema devuelto por la API de Zoho Desk, no el número de referencia legible que se muestra en el portal de soporte. ^[2]
• Completitud de la respuesta: Si esperas múltiples adjuntos pero solo ves una lista parcial, comprueba si es necesario suministrar parámetros de paginación a través del argumento p para recuperar todas las páginas. ^[3]