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

Listar los archivos adjuntos de un ticket en Zoho Desk es sencillo a través de la API REST: envía una solicitud GET al sub-recurso de adjuntos de cualquier ticket y la plataforma devuelve todos los archivos asociados a ese registro.

Por qué es importante

Cuando construyes integraciones, automatizaciones o flujos de trabajo de auditoría, a menudo necesitas inspeccionar cada archivo que un cliente ha enviado junto con su solicitud de soporte. Recuperar la lista de adjuntos de forma programática te permite sincronizar archivos con almacenamiento externo, validar cargas o mostrarlos dentro de un portal personalizado, sin necesidad de que un agente abra el ticket manualmente.

Paso a paso

Paso 1. Confirma que tus permisos OAuth están configurados.

Antes de realizar cualquier llamada a la API, verifica que tu aplicación conectada tenga concedido el alcance Desk.tickets.READ (como mínimo) o el alcance más amplio Desk.tickets.ALL. Sin estos, la solicitud será rechazada en la capa de autorización. ^[8]

Paso 2. Identifica el ID del ticket.

Cada ticket de Zoho Desk tiene un ticketId numérico único. Puedes obtenerlo de una llamada previa a la lista de tickets, desde la URL del ticket en la interfaz de Desk o desde el payload de un webhook. Guarda este valor: es el parámetro de ruta clave para el siguiente paso.

Paso 3. Envía la solicitud para listar adjuntos.

Realiza una solicitud HTTP GET al siguiente endpoint, sustituyendo el identificador real de tu ticket:

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

El objeto de parámetro de consulta opcional p puede contener argumentos de paginación o filtrado compatibles con la API de Zoho Desk. ^[2][3]

Una implementación mínima en Python 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 método pasa None como cuerpo de la solicitud (correcto para un GET) y reenvía cualquier parámetro de consulta a través de p. ^[2]

Paso 4. Analiza la respuesta.

La API devuelve una colección de objetos de adjunto. Cada objeto incluye normalmente metadatos como el nombre del archivo, el tamaño y un ID de referencia que puedes usar para operaciones posteriores.

Paso 5. Obtén un adjunto específico cuando sea necesario.

Si solo necesitas los detalles de un archivo concreto, utiliza la variante de recurso único añadiendo el attachmentId a la ruta:

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

Esto es útil cuando ya conoces el identificador de una llamada de lista anterior y quieres evitar procesar toda la colección. ^[5]

Paso 6. (Opcional) Recupera adjuntos vinculados a un borrador de transición.

Si tu flujo de trabajo utiliza transiciones de ticket (por ejemplo, etapas de aprobación), los adjuntos también pueden estar asociados a una transición específica. Usa el endpoint dedicado:

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

Esto es independiente de la lista principal de adjuntos y solo aplica cuando hay un borrador de transición en curso. ^[7]

Errores comunes

• Alcance ausente o incorrecto. El alcance Desk.tickets.READ debe estar presente en tu token OAuth. Si recibes una respuesta 401 o 403, revisa los alcances configurados para tu cliente y regenera el token de acceso. ^[8]
• Confundir el ticketId con el número de ticket legible por humanos. El parámetro de ruta debe ser el ID numérico interno, no la referencia estilo #1234 que se muestra en la interfaz. Usar el número de visualización devolverá un 404.
• Olvidar la paginación. Si un ticket tiene muchos adjuntos, la respuesta puede estar paginada. Pasa el parámetro de página adecuado a través del diccionario p para recuperar las páginas siguientes. ^[2][3]
• Subir vs. listar. La misma ruta (/api/v1/tickets/{ticketId}/attachments) se usa tanto para listar (GET) como para subir (POST). Asegúrate de que tu integración utiliza el verbo HTTP correcto; un POST a ese endpoint creará un nuevo adjunto en lugar de devolver los existentes. ^[4][6]

Qué verificar

• Verificación de alcances: Confirma que Desk.tickets.READ o Desk.tickets.ALL aparece en el token OAuth activo antes de pasar a producción. ^[8]
• Estructura de la respuesta: Registra la respuesta sin procesar de la primera llamada para confirmar que los campos de metadatos del adjunto (nombre, tamaño, ID) coinciden con lo que espera tu código posterior. ^[2][5]
• Origen del ID del ticket: Rastrea de dónde proviene tu ticketId y valida que es el ID interno del sistema, no una referencia de visualización, para evitar errores 404 silenciosos.

---

*Beam Help es un recurso de soporte experto independiente para productos Zoho — no somos el soporte oficial de Zoho. Para problemas a nivel de plataforma, consulta siempre la documentación oficial de la API de Zoho Desk.*