Come recuperare un allegato di un ticket in Zoho Desk

Per recuperare un allegato di un ticket in Zoho Desk tramite API sono necessari due identificatori — l'ID del ticket e l'ID dell'allegato — e una semplice richiesta GET all'endpoint degli allegati.

Perché è importante

Quando si creano integrazioni o automazioni attorno a Zoho Desk, spesso è necessario recuperare programmaticamente i file allegati ai ticket di supporto — ad esempio per archiviarli, inoltrarli a un altro sistema o esaminarne il contenuto. Conoscere l'endpoint corretto e l'ordine delle operazioni (prima elencare, poi recuperare) consente di risparmiare molto tempo nel debug e mantiene l'integrazione affidabile.

Passo dopo passo

Passo 1. Recupera il tuo ticket ID.

Prima di effettuare qualsiasi richiesta relativa agli allegati, conferma il ticketId del ticket con cui stai lavorando. Questo è l'identificatore univoco che Zoho Desk assegna a ogni ticket di supporto ed è richiesto in ogni chiamata API relativa agli allegati.^[1]

Passo 2. Elenca tutti gli allegati del ticket.

Se non conosci già l'attachmentId, invia prima una richiesta GET all'endpoint di elenco:

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

Passa il ticketId come parametro di percorso. È possibile fornire un dizionario di parametri query opzionale (p) per la paginazione o il filtraggio.^[3] In Python si presenta così:

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

La risposta includerà i metadati di ogni allegato, compreso il suo attachmentId, che sarà necessario nel passaggio successivo.^[3]

Passo 3. Recupera l'allegato specifico.

Una volta ottenuti entrambi gli identificatori, chiama l'endpoint per il singolo allegato:

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

Sostituisci {ticketId} e {attachmentId} con i valori reali. Il parametro opzionale p può contenere eventuali opzioni di query aggiuntive necessarie per la tua integrazione.^[1] In Python:

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

L'oggetto di risposta contiene i dettagli dell'allegato per quel file specifico.^[1]

Passo 4. (Opzionale) Recupera gli allegati associati a una bozza di transizione.

Se il file di cui hai bisogno è associato a una transizione di workflow anziché al corpo del ticket, utilizza un endpoint diverso che richiede anche un transitionId:

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

Fornisci tutti e tre i parametri di percorso — ticketId, transitionId e opzionalmente p — per recuperare gli allegati appartenenti a quella bozza di transizione.^[4]

Passo 5. (Opzionale) Carica o elimina allegati secondo necessità.

Per completezza, il nostro team segnala che lo stesso percorso /api/v1/tickets/{ticketId}/attachments supporta richieste POST per aggiungere un nuovo file (con un payload data) e richieste DELETE al sotto-percorso /{attachmentId} per rimuovere un file esistente.^[6][8] Queste operazioni seguono le stesse convenzioni di ID descritte sopra.

Errori comuni

• Ordine degli ID errato. Il percorso posiziona sempre ticketId prima di attachmentId. Invertirli produrrà una richiesta fallita o una risposta 404.^[1]
• Saltare il passaggio di elenco. Tentare di chiamare l'endpoint per il singolo allegato senza prima confermare il corretto attachmentId tramite l'endpoint di elenco è una fonte comune di errori. Elenca sempre prima se non sei sicuro.^[3]
• Allegati di transizione vs. allegati del ticket. I file allegati durante una bozza di transizione di workflow si trovano nel percorso /transitions/{transitionId}/attachments, non nel percorso standard degli allegati del ticket. Utilizzare l'endpoint sbagliato restituirà un risultato vuoto o inatteso.^[4]
• Confondere caricamento e recupero. L'endpoint POST su /api/v1/tickets/{ticket_id}/attachments serve per caricare nuovi file, non per scaricare quelli esistenti. Usa GET per il recupero.^[7]

Cosa verificare

• Entrambi gli ID sono presenti e corretti — conferma che ticketId e attachmentId siano validi prima di chiamare l'endpoint GET.^[1]
• L'ambito dell'allegato è corretto — verifica se il file appartiene al corpo del ticket o a una bozza di transizione e utilizza l'endpoint appropriato di conseguenza.^[3][4]
• Le tue credenziali API dispongono delle autorizzazioni necessarie — assicurati che il token OAuth o la chiave API utilizzata dalla tua integrazione abbia accesso in lettura agli allegati dei ticket Zoho Desk prima di eseguire il debug degli errori di risposta.^[1]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non è il supporto ufficiale Zoho. Verifica sempre con la documentazione ufficiale di Zoho per le ultime modifiche agli endpoint.*