Come elencare gli allegati di un ticket in Zoho Desk

Elencare gli allegati di un ticket in Zoho Desk è semplice tramite l'API REST: invia una richiesta GET alla sotto-risorsa degli allegati di qualsiasi ticket e la piattaforma restituisce tutti i file associati a quel record.

Perché è importante

Quando si creano integrazioni, automazioni o flussi di lavoro di audit, spesso è necessario esaminare ogni file che un cliente ha inviato insieme alla propria richiesta di assistenza. Recuperare l'elenco degli allegati in modo programmatico consente di copiare i file su uno storage esterno, validare i caricamenti o visualizzarli all'interno di un portale personalizzato — senza richiedere a un agente di aprire manualmente il ticket.

Procedura passo dopo passo

Passaggio 1. Verifica che gli scope OAuth siano configurati.

Prima di effettuare qualsiasi chiamata API, assicurati che alla tua app connessa sia stato concesso lo scope Desk.tickets.READ (come minimo) o lo scope più ampio Desk.tickets.ALL. Senza questi, la richiesta verrà rifiutata a livello di autorizzazione. ^[8]

Passaggio 2. Identifica l'ID del ticket.

Ogni ticket di Zoho Desk ha un ticketId numerico univoco. Puoi ottenerlo da una precedente chiamata all'elenco dei ticket, dall'URL del ticket nell'interfaccia di Desk o da un payload webhook. Tieni questo valore a portata di mano — è il parametro chiave del percorso per il passaggio successivo.

Passaggio 3. Invia la richiesta di elenco allegati.

Esegui una GET HTTP all'endpoint seguente, sostituendo il tuo identificatore di ticket reale:

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

L'oggetto opzionale di parametri query p può contenere argomenti di paginazione o filtraggio supportati dall'API di Zoho Desk. ^[2][3]

Un'implementazione minimale in Python è la seguente:

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

Il metodo passa None come corpo della richiesta (corretto per una GET) e inoltra eventuali parametri query tramite p. ^[2]

Passaggio 4. Analizza la risposta.

L'API restituisce una raccolta di oggetti allegato. Ogni oggetto include in genere metadati come il nome del file, la dimensione e un ID di riferimento utilizzabile per operazioni successive.

Passaggio 5. Recupera un singolo allegato quando necessario.

Se hai bisogno solo dei dettagli di un file specifico, utilizza la variante a risorsa singola aggiungendo l'attachmentId al percorso:

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

Questo è utile quando conosci già l'identificatore da una precedente chiamata all'elenco e vuoi evitare di elaborare l'intera raccolta. ^[5]

Passaggio 6. (Facoltativo) Recupera gli allegati associati a una bozza di transizione.

Se il tuo flusso di lavoro utilizza le transizioni dei ticket (ad esempio, fasi di approvazione), gli allegati possono essere anche limitati a una transizione specifica. Utilizza l'endpoint dedicato:

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

Questo è separato dall'elenco principale degli allegati e si applica solo quando è in corso una bozza di transizione. ^[7]

Errori comuni

• Scope mancante o errato. Lo scope Desk.tickets.READ deve essere presente nel token OAuth. Se ricevi una risposta 401 o 403, verifica nuovamente gli scope configurati per il tuo client e rigenera il token di accesso. ^[8]
• Confondere il ticketId con il numero di ticket leggibile dall'utente. Il parametro del percorso deve essere l'ID numerico interno, non il riferimento in stile #1234 mostrato nell'interfaccia. Utilizzare il numero visualizzato restituirà un errore 404.
• Dimenticare la paginazione. Se un ticket ha molti allegati, la risposta potrebbe essere paginata. Passa il parametro di pagina appropriato tramite il dizionario p per recuperare le pagine successive. ^[2][3]
• Caricamento vs. elenco. Lo stesso percorso (/api/v1/tickets/{ticketId}/attachments) viene utilizzato sia per elencare (GET) che per caricare (POST). Assicurati che la tua integrazione utilizzi il verbo HTTP corretto: una POST su quell'endpoint creerà un nuovo allegato anziché restituire quelli esistenti. ^[4][6]

Cosa verificare

• Verifica degli scope: Conferma che Desk.tickets.READ o Desk.tickets.ALL sia presente nel token OAuth attivo prima di andare in produzione. ^[8]
• Struttura della risposta: Registra la risposta grezza della prima chiamata per verificare che i campi dei metadati degli allegati (nome, dimensione, ID) corrispondano a quanto si aspetta il codice a valle. ^[2][5]
• Origine dell'ID ticket: Traccia da dove proviene il tuo ticketId e verifica che sia l'ID di sistema interno, non un riferimento visualizzato, per evitare errori 404 silenziosi.

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho — non siamo il supporto ufficiale di Zoho. Per problemi a livello di piattaforma, fai sempre riferimento alla documentazione ufficiale dell'API di Zoho Desk.*