Come eliminare un allegato da un ticket in Zoho Desk

L'eliminazione di un allegato da un ticket in Zoho Desk avviene tramite una chiamata API DELETE che individua l'allegato specifico tramite il suo ID all'interno di un determinato ticket. A seconda di dove si trova l'allegato — sul ticket stesso, su un thread o su una bozza di transizione — verrà utilizzato un endpoint leggermente diverso.

Perché è importante

Gli allegati sui ticket di supporto possono contenere dati sensibili dei clienti, file obsoleti o semplicemente elementi superflui che rendono più difficile la gestione. La possibilità di rimuoverli in modo programmatico è essenziale per i flussi di lavoro di pulizia automatizzata, le politiche di conservazione dei dati orientate alla conformità, o qualsiasi integrazione che gestisce il contenuto dei ticket su larga scala. In qualità di supporto esperto indipendente per Zoho (non supporto ufficiale Zoho), Beam Help ti guida attraverso ogni variante di questa operazione.

Procedura passo dopo passo

Passaggio 1. Verifica che gli scope OAuth siano configurati correttamente.

Prima di effettuare qualsiasi chiamata API distruttiva, verifica che all'app connessa sia stato concesso lo scope Desk.tickets.DELETE (e Desk.tickets.ALL se desideri i permessi completi sui ticket). Senza questi scope la richiesta verrà rifiutata a livello di autorizzazione. ^[6]

Passaggio 2. Identifica l'allegato che vuoi rimuovere.

Hai bisogno di due ID: il ticketId del ticket padre e l'attachmentId del file che vuoi rimuovere. Se non sei sicuro dell'attachmentId, recuperalo prima con una richiesta GET a /api/v1/tickets/{ticketId}/attachments/{attachmentId} per confermare di avere il record corretto prima di eliminarlo. ^[8]

Passaggio 3. Elimina un allegato a livello di ticket.

Invia una richiesta DELETE al seguente endpoint, sostituendo i tuoi ID reali:

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

In Python si presenta così:

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

Una chiamata riuscita rimuove l'allegato dal record del ticket in modo definitivo. ^[1]

Passaggio 4. (Alternativa) Elimina un allegato su un thread del ticket.

Se il file è stato caricato come parte di un thread di risposta o di nota anziché direttamente sul ticket, devi includere il thread_id nel percorso. Usa invece questo endpoint:

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

In Python:

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

Questa variante richiede tre parametri di percorso anziché due, quindi assicurati di avere il thread_id corretto prima di chiamarla. ^[3]

Passaggio 5. (Alternativa) Elimina un allegato da una bozza di transizione.

Se il tuo flusso di lavoro utilizza le transizioni dei ticket e un allegato è stato aggiunto a una bozza di transizione, un endpoint separato gestisce questo caso:

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

In Python:

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

Questo endpoint è specificamente dedicato agli allegati delle bozze di transizione e non influirà sugli allegati archiviati direttamente sul ticket o sui suoi thread. ^[4]

---

Errori comuni

• Endpoint errato per il tipo di allegato. L'API di Zoho Desk espone percorsi distinti per gli allegati a livello di ticket, a livello di thread e a livello di bozza di transizione. Utilizzare l'endpoint a livello di ticket (/tickets/{ticketId}/attachments/{attachmentId}) quando il file appartiene effettivamente a un thread restituirà un errore o una risposta "non trovato". Verifica sempre dove è stato originariamente caricato l'allegato. ^[1][3]

• Scope mancante o errato. Lo scope Desk.tickets.DELETE deve essere incluso esplicitamente nella richiesta del token OAuth. Avere solo Desk.tickets.READ o Desk.tickets.WRITE non è sufficiente per l'eliminazione. Rivedi la configurazione degli scope e ri-autorizza se necessario. ^[6]

• Confusione tra allegati dei ticket e allegati degli account. Se stai lavorando in un contesto che gestisce anche i record degli account, tieni presente che gli allegati a livello di account utilizzano un percorso completamente diverso (/api/v1/accounts/{accountId}/attachments/{attachmentId}) e non devono essere confusi con gli endpoint degli allegati dei ticket. ^[7]

• Operazione irreversibile. Una chiamata DELETE su un allegato è permanente. Non esiste un cestino né la possibilità di annullare l'operazione. Usa sempre l'endpoint GET per verificare l'attachmentId corretto prima di procedere con l'eliminazione. ^[8]

---

Cosa verificare

• Conferma che l'allegato sia stato rimosso chiamando GET /api/v1/tickets/{ticketId}/attachments/{attachmentId} dopo l'eliminazione — dovrebbe restituire un 404 o una risposta vuota, indicando che il file è stato rimosso. ^[8]
• Verifica la copertura degli scope nelle impostazioni del tuo client OAuth per assicurarti che Desk.tickets.DELETE (o Desk.tickets.ALL) sia presente e che il token sia stato aggiornato dopo l'aggiunta dello scope. ^[6]
• Controlla che sia stata utilizzata la variante di percorso corretta — a livello di ticket, di thread o di transizione — per assicurarti che sia stato individuato l'allegato giusto e che nessun file indesiderato sia stato interessato. ^[1][3][4]