Come recuperare gli allegati di transizione in Zoho Desk

Il recupero degli allegati di transizione in Zoho Desk richiede una semplice richiesta GET all'API REST di Desk, fornendo sia l'identificatore del ticket sia l'identificatore della transizione per ottenere tutti i file allegati a una bozza di transizione.

Perché è importante

Quando un ticket di Zoho Desk avanza attraverso un blueprint o un flusso di lavoro, gli agenti possono allegare documenti di supporto direttamente a una bozza di transizione. Se hai bisogno di verificare quei file, visualizzarli in un portale personalizzato o elaborarli in modo programmatico, devi sapere come interrogare l'endpoint corretto. Questo è anche un passaggio preliminare necessario prima di decidere se eliminare un allegato specifico da una bozza di transizione.

Procedura passo dopo passo

Passaggio 1. Verifica di disporre di un token di accesso OAuth valido con scope per Zoho Desk. Il token deve essere ottenuto tramite il flusso OAuth standard di Zoho — scambiando un codice di autorizzazione con un token di accesso — prima che qualsiasi chiamata API possa avere successo. ^[8]

Passaggio 2. Identifica i due identificatori chiave necessari: il ticketId del ticket in questione e il transitionId della specifica transizione blueprint di cui vuoi recuperare gli allegati. Entrambi i valori sono stringhe e devono essere forniti nel percorso URL. ^[1]

Passaggio 3. Invia una richiesta GET al seguente endpoint, sostituendo i valori reali ai segnaposto:

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

Questa operazione è documentata internamente come op15getattachmentof_transition ed è descritta come "Get Attachment of Transition Draft". ^[1]

Passaggio 4. Facoltativamente, passa un parametro p come dizionario nella query string se hai bisogno di applicare opzioni di paginazione o filtro supportate dall'endpoint. Quando non sono necessari parametri aggiuntivi, questo argomento può essere omesso o impostato su None. ^[1]

Passaggio 5. In Python, il pattern di chiamata è il seguente:

result = client.op_15_get_attachment_of_transition(
    ticketId="123456",
    transitionId="789012",
    p=None  # or pass a dict of query params
)

La richiesta sottostante è una semplice HTTP GET senza corpo della richiesta. ^[1]

Passaggio 6. Analizza la risposta per ottenere l'elenco degli oggetti allegato associati a quella bozza di transizione. Ogni oggetto conterrà i metadati necessari per identificare i singoli allegati — avrai bisogno del valore attachmentId da questa risposta se in seguito intendi rimuovere un file specifico. ^[4]

Errori comuni

• Ordine degli identificatori errato. Il percorso richiede prima il ticketId, poi il transitionId. Invertirli produrrà un errore 404 o una risposta vuota inattesa. Verifica l'ordine rispetto alla firma dell'endpoint. ^[1]
• Token OAuth scaduto o assente. Tutte le chiamate all'API di Zoho Desk richiedono un token di accesso valido. Se il token è scaduto, aggiornalo prima di riprovare — un token scaduto restituirà un errore di autenticazione anziché i dati degli allegati. ^[8]
• Confusione tra "recupero" ed "eliminazione". L'endpoint di recupero (GET …/attachments) e l'endpoint di eliminazione (DELETE …/attachments/{attachmentId}) condividono lo stesso percorso base, ma differiscono per metodo HTTP e per la presenza di attachmentId. Usare il metodo sbagliato non produrrà alcun effetto oppure rimuoverà permanentemente un file. ^[4]

Cosa verificare

• Verifica che entrambi gli ID siano corretti — conferma che ticketId e transitionId esistano nella tua organizzazione Zoho Desk prima di effettuare la chiamata, poiché un ID non valido restituirà un errore anziché un elenco vuoto. ^[1]
• Conferma che la risposta contenga i metadati degli allegati — se alla bozza di transizione non è allegato alcun file, l'array della risposta sarà vuoto; questo è il comportamento previsto, non un errore. ^[1]
• Annota i valori attachmentId — se sono necessarie azioni successive come l'eliminazione, acquisisci quegli ID da questa risposta ora, poiché l'operazione di eliminazione li richiede esplicitamente. ^[4]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non rappresenta il supporto ufficiale di Zoho. Testa sempre le chiamate API in un ambiente sandbox prima di eseguirle sui dati di produzione.*