Come elencare gli allegati di un ticket in Zoho Desk

Elencare tutti gli allegati di un ticket Zoho Desk è semplice una volta che conosci il corretto endpoint API e hai i giusti scope OAuth configurati. Questo articolo ti guida attraverso la chiamata esatta e la configurazione necessaria — da Beam Help, il tuo supporto esperto indipendente per Zoho (non il supporto ufficiale Zoho).

Perché è importante

Quando si creano integrazioni, automazioni o flussi di lavoro di audit, spesso è necessario recuperare programmaticamente ogni file allegato a un ticket di supporto. Che tu stia sincronizzando gli allegati con un archivio documenti esterno, verificando che i file richiesti siano stati caricati, o semplicemente visualizzandoli in un portale personalizzato, sapere come chiamare correttamente l'endpoint list-attachments consente di risparmiare molto tempo in fase di debug.

Procedura passo dopo passo

Passaggio 1. Verifica gli scope OAuth.

Prima di effettuare qualsiasi chiamata API, assicurati che l'applicazione connessa abbia ricevuto le autorizzazioni necessarie a livello di ticket. Come minimo, il tuo token OAuth deve includere Desk.tickets.READ — e idealmente Desk.tickets.ALL — per recuperare i dati del ticket inclusi gli allegati. ^[8]

Passaggio 2. Identifica l'ID del ticket.

Hai bisogno del ticketId (o ticket_id) univoco del ticket di cui vuoi elencare gli allegati. Questo è l'identificatore interno di Zoho Desk, non il numero di ticket leggibile dall'utente mostrato nell'interfaccia. Puoi ottenerlo da una precedente risposta di ricerca o creazione del ticket. ^[2]

Passaggio 3. Invia una richiesta GET all'endpoint degli allegati.

Esegui una richiesta HTTP GET al seguente percorso, sostituendo il tuo identificatore di ticket effettivo:

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

Questa operazione — denominata listticketattachments — restituisce la raccolta di file associati a quel ticket. ^[2] Un'operazione equivalente denominata list_attachments utilizza lo stesso metodo HTTP e la stessa struttura del percorso, confermando che questa è la route canonica. ^[3]

In Python, utilizzando un wrapper client preconfigurato, la chiamata si presenta così:

def list_ticket_attachments(self, ticketId: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/tickets/{ticketId}/attachments", p, None)

Il parametro opzionale p può contenere argomenti della query string come i controlli di paginazione. ^[2]

Passaggio 4. Gestisci la paginazione se necessario.

L'endpoint accetta un parametro p per la paginazione. Se un ticket ha molti allegati, passa i valori appropriati di pagina o offset in quel dizionario per recuperare le pagine successive dei risultati. [^2, ^3]

Passaggio 5. Accedi a un singolo allegato (opzionale).

Se hai bisogno dei metadati completi di un file specifico dopo averli elencati, utilizza l'endpoint per il singolo allegato aggiungendo l'attachmentId al percorso:

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

Questa operazione getticketattachment restituisce informazioni dettagliate su quel singolo file. ^[5]

Passaggio 6. Recupera gli allegati su una bozza di transizione (avanzato, opzionale).

Se il tuo flusso di lavoro utilizza le transizioni dei ticket e hai bisogno degli allegati relativi a una specifica bozza di transizione anziché al ticket stesso, esiste un endpoint separato:

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

Questa è un'operazione distinta e deve essere utilizzata solo quando hai specificamente bisogno dei dati degli allegati a livello di transizione. ^[7]

Errori comuni

• Scope OAuth mancante o insufficiente. Se il tuo token include solo Desk.tickets.WRITE o Desk.tickets.CREATE ma non Desk.tickets.READ o Desk.tickets.ALL, l'API rifiuterà la richiesta. Verifica sempre l'elenco completo degli scope nella tua configurazione OAuth. ^[8]

• Confusione tra numero di ticket e ID del ticket. Il ticketId nel percorso URL è l'identificatore interno generato dal sistema. Utilizzare il numero di ticket visualizzato (ad es. "TKT-1042") produrrà un errore 404 o di record non valido. Recupera l'ID corretto da una precedente risposta API.

• Dimenticare di aggiungere allegati prima di elencarli. Se stai eseguendo dei test e l'elenco risulta vuoto, verifica che i file siano stati effettivamente caricati. Gli allegati vengono aggiunti tramite una richiesta POST allo stesso percorso /api/v1/tickets/{ticketId}/attachments. [^4, ^6]

• Allegati di transizione vs. allegati del ticket. L'endpoint per le bozze di transizione (/transitions/{transitionId}/attachments) non è intercambiabile con l'endpoint principale degli allegati del ticket. Chiamare quello sbagliato restituirà un insieme di risultati vuoto o non correlato. ^[7]

Cosa verificare

• Verifica degli scope: Conferma che Desk.tickets.READ o Desk.tickets.ALL sia presente nell'elenco degli scope del tuo token OAuth attivo prima di effettuare la chiamata. ^[8]
• ID ticket corretto: Verifica che il ticketId che stai passando sia l'ID di sistema interno restituito dall'API di Zoho Desk, non il numero di riferimento leggibile dall'utente mostrato nel portale di supporto. ^[2]
• Completezza della risposta: Se ti aspetti più allegati ma ne vedi solo un elenco parziale, verifica se è necessario fornire i parametri di paginazione tramite l'argomento p per recuperare tutte le pagine. ^[3]