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

Eliminar un archivo adjunto de un ticket en Zoho Desk se realiza mediante una llamada a la API con el método DELETE, que apunta al adjunto específico por su ID dentro de un ticket determinado. Dependiendo de dónde se encuentre el adjunto — en el propio ticket, en un hilo o en un borrador de transición — utilizarás un endpoint ligeramente diferente.

Por qué esto es importante

Los adjuntos en los tickets de soporte pueden contener datos sensibles de clientes, archivos desactualizados o simplemente elementos que dificultan la clasificación. Poder eliminarlos de forma programática es esencial para flujos de trabajo de limpieza automatizada, políticas de retención de datos orientadas al cumplimiento normativo, o cualquier integración que gestione el contenido de los tickets a gran escala. Como soporte experto independiente para Zoho (no soporte oficial de Zoho), Beam Help te guía a través de cada variante de esta operación.

Paso a paso

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

Antes de realizar cualquier llamada a la API que implique eliminación, verifica que tu aplicación conectada tenga concedido el alcance Desk.tickets.DELETE (y Desk.tickets.ALL si deseas permisos completos sobre los tickets). Sin estos alcances, la solicitud será rechazada en la capa de autorización. ^[6]

Paso 2. Identifica el adjunto que deseas eliminar.

Necesitas dos IDs: el ticketId del ticket principal y el attachmentId del archivo que quieres eliminar. Si no estás seguro del attachmentId, recupéralo primero con una solicitud GET a /api/v1/tickets/{ticketId}/attachments/{attachmentId} para confirmar que tienes el registro correcto antes de eliminarlo. ^[8]

Paso 3. Elimina un adjunto de nivel superior del ticket.

Envía una solicitud DELETE al siguiente endpoint, sustituyendo tus IDs reales:

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

En Python, esto se vería así:

response = client.delete_ticket_attachment(
    ticketId="your_ticket_id",
    attachmentId="your_attachment_id"
)

Una llamada exitosa elimina el adjunto del registro del ticket por completo. ^[1]

Paso 4. (Alternativa) Elimina un adjunto en un hilo del ticket.

Si el archivo fue cargado como parte de un hilo de respuesta o nota en lugar de directamente en el ticket, debes incluir el thread_id en la ruta. Usa este endpoint en su lugar:

DELETE /api/v1/tickets/{ticket_id}/threads/{thread_id}/attachments/{attachment_id}

En Python:

response = client.delete_attachment(
    ticket_id="your_ticket_id",
    thread_id="your_thread_id",
    attachment_id="your_attachment_id"
)

Esta variante requiere tres parámetros de ruta en lugar de dos, así que asegúrate de tener el thread_id correcto antes de llamarla. ^[3]

Paso 5. (Alternativa) Elimina un adjunto de un borrador de transición.

Si tu flujo de trabajo utiliza transiciones de tickets y se añadió un adjunto a un borrador de transición, un endpoint separado gestiona ese caso:

DELETE /api/v1/tickets/{ticketId}/transitions/{transitionId}/attachments/{attachmentId}

En Python:

response = client.op_16_delete_attachment_of_transition(
    ticketId="your_ticket_id",
    transitionId="your_transition_id",
    attachmentId="your_attachment_id"
)

Este endpoint está específicamente orientado a los adjuntos de borradores de transición y no afectará a los adjuntos almacenados directamente en el ticket o en sus hilos. ^[4]

---

Errores comunes

• Endpoint incorrecto para el tipo de adjunto. La API de Zoho Desk expone rutas distintas para adjuntos a nivel de ticket, adjuntos a nivel de hilo y adjuntos de borradores de transición. Usar el endpoint de nivel de ticket (/tickets/{ticketId}/attachments/{attachmentId}) cuando el archivo pertenece en realidad a un hilo devolverá un error o una respuesta de "no encontrado". Confirma siempre dónde fue cargado originalmente el adjunto. ^[1][3]

• Alcance ausente o incorrecto. El alcance Desk.tickets.DELETE debe incluirse explícitamente en tu solicitud de token OAuth. Tener únicamente Desk.tickets.READ o Desk.tickets.WRITE no es suficiente para la eliminación. Revisa la configuración de tus alcances y vuelve a autorizar si es necesario. ^[6]

• Confundir adjuntos de tickets con adjuntos de cuentas. Si trabajas en un contexto que también gestiona registros de cuentas, ten en cuenta que los adjuntos a nivel de cuenta utilizan una ruta completamente diferente (/api/v1/accounts/{accountId}/attachments/{attachmentId}) y no deben confundirse con los endpoints de adjuntos de tickets. ^[7]

• Operación irreversible. Una llamada DELETE sobre un adjunto es permanente. No existe papelera de reciclaje ni opción de deshacer. Utiliza siempre el endpoint GET para verificar el attachmentId correcto antes de ejecutar la eliminación. ^[8]

---

Qué verificar

• Confirma que el adjunto ha sido eliminado llamando a GET /api/v1/tickets/{ticketId}/attachments/{attachmentId} después de la eliminación — debería devolver un 404 o una respuesta vacía, lo que indica que el archivo ha sido eliminado. ^[8]
• Verifica la cobertura de alcances en la configuración de tu cliente OAuth para asegurarte de que Desk.tickets.DELETE (o Desk.tickets.ALL) está presente y de que el token ha sido actualizado desde que se añadió el alcance. ^[6]
• Comprueba que se utilizó la variante de ruta correcta — nivel de ticket, nivel de hilo o nivel de transición — para garantizar que se apuntó al adjunto correcto y que no se vieron afectados archivos no deseados. ^[1][3][4]