Cómo recuperar un archivo adjunto de un ticket en Zoho Desk

Recuperar un archivo adjunto de un ticket en Zoho Desk a través de la API requiere dos identificadores — el ID del ticket y el ID del adjunto — y una solicitud GET sencilla al endpoint de adjuntos.

Por qué esto es importante

Al crear integraciones o automatizaciones en torno a Zoho Desk, a menudo necesitas obtener mediante programación los archivos adjuntos a los tickets de soporte — por ejemplo, para archivarlos, reenviarlos a otro sistema o inspeccionar su contenido. Conocer el endpoint correcto y el orden de las operaciones (listar primero, luego obtener) ahorra un tiempo considerable de depuración y mantiene tu integración fiable.

Paso a paso

Paso 1. Obtén el ID de tu ticket.

Antes de realizar cualquier solicitud de adjunto, confirma el ticketId del ticket con el que estás trabajando. Este es el identificador único que Zoho Desk asigna a cada ticket de soporte y es obligatorio en todas las llamadas a la API relacionadas con adjuntos.^[1]

Paso 2. Lista todos los adjuntos del ticket.

Si aún no conoces el attachmentId, envía primero una solicitud GET al endpoint de listado:

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

Pasa el ticketId como parámetro de ruta. Se puede incluir un diccionario de parámetros de consulta opcional (p) para paginación o filtrado.^[3] En Python, esto se ve así:

attachments = client.list_ticket_attachments(ticketId="123456")

La respuesta incluirá los metadatos de cada adjunto, incluyendo su attachmentId, que necesitarás en el siguiente paso.^[3]

Paso 3. Recupera el adjunto específico.

Una vez que tengas ambos identificadores, llama al endpoint de adjunto individual:

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

Reemplaza {ticketId} y {attachmentId} con los valores reales. El parámetro opcional p puede incluir cualquier opción de consulta adicional que necesite tu integración.^[1] En Python:

attachment = client.get_ticket_attachment(
    ticketId="123456",
    attachmentId="789"
)

El objeto de respuesta contiene los detalles del adjunto para ese archivo específico.^[1]

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

Si el archivo que necesitas está asociado a una transición de flujo de trabajo en lugar del cuerpo del ticket, utiliza un endpoint diferente que también requiere un transitionId:

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

Proporciona los tres parámetros de ruta — ticketId, transitionId y opcionalmente p — para recuperar los adjuntos pertenecientes a ese borrador de transición.^[4]

Paso 5. (Opcional) Sube o elimina adjuntos según sea necesario.

A modo de referencia completa, nuestro equipo señala que la misma ruta /api/v1/tickets/{ticketId}/attachments admite solicitudes POST para añadir un nuevo archivo (con un payload data) y solicitudes DELETE a la subruta /{attachmentId} para eliminar uno existente.^[6][8] Estas operaciones siguen las mismas convenciones de ID descritas anteriormente.

Errores comunes

• Orden incorrecto de los IDs. La ruta siempre coloca el ticketId antes del attachmentId. Intercambiarlos resultará en una solicitud fallida o una respuesta 404.^[1]
• Omitir el paso de listado. Intentar llamar al endpoint de adjunto individual sin confirmar primero el attachmentId correcto a través del endpoint de listado es una fuente habitual de errores. Siempre lista primero si no estás seguro.^[3]
• Adjuntos de transición vs. adjuntos de ticket. Los archivos adjuntados durante un borrador de transición de flujo de trabajo se encuentran bajo la ruta /transitions/{transitionId}/attachments, no en la ruta estándar de adjuntos del ticket. Usar el endpoint incorrecto devolverá un resultado vacío o inesperado.^[4]
• Confundir la subida con la recuperación. El endpoint POST en /api/v1/tickets/{ticket_id}/attachments sirve para subir nuevos archivos, no para descargar los existentes. Usa GET para la recuperación.^[7]

Qué verificar

• Ambos IDs están presentes y son correctos — confirma que ticketId y attachmentId son válidos antes de llamar al endpoint GET.^[1]
• El alcance del adjunto es el correcto — verifica si el archivo pertenece al cuerpo del ticket o a un borrador de transición, y utiliza el endpoint apropiado en consecuencia.^[3][4]
• Tus credenciales de API tienen los permisos necesarios — asegúrate de que el token OAuth o la clave de API que usa tu integración tiene acceso de lectura a los adjuntos de tickets de Zoho Desk antes de depurar errores de respuesta.^[1]

---

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