Come elencare i ticket per account in Zoho Desk

Elencare i ticket associati a un account specifico in Zoho Desk è semplice una volta che disponi dell'ID account corretto e degli scope API appropriati. Questa guida illustra l'endpoint esatto e i passaggi di configurazione utilizzati dal nostro team.

Perché è importante

Nella gestione del supporto enterprise, spesso è necessario visualizzare tutti i ticket aperti o storici legati a una singola azienda, anziché a un singolo contatto. Recuperare i ticket per account offre ai responsabili del supporto una visione consolidata dell'intera cronologia di supporto di un'organizzazione cliente, rendendo molto più rapide le decisioni di escalation e le revisioni degli SLA.

Passo dopo passo

Passo 1. Verifica che i tuoi scope OAuth includano l'accesso ai ticket e agli account di Desk.

Prima di effettuare qualsiasi chiamata API, verifica che il token OAuth di Zoho Desk connesso sia stato concesso almeno con gli scope Desk.tickets.READ e Desk.contacts.READ. Senza questi, la richiesta verrà rifiutata a livello di autorizzazione. Il nostro team consiglia di includere anche Desk.tickets.ALL in modo che le operazioni di scrittura siano disponibili se necessario in seguito. ^[2]

Passo 2. Identifica l'ID account che vuoi interrogare.

Accedi al tuo portale Zoho Desk e apri la sezione Account. Apri il record dell'account specifico e copia l'ID numerico dall'URL o dal pannello dei dettagli del record. Questo è il valore account_id che passerai all'endpoint. Se stai lavorando in modo programmatico, puoi recuperarlo anche navigando all'elenco degli account al percorso /accounts nel tuo portale. ^[1]

Passo 3. Chiama l'endpoint per elencare i ticket per account.

Invia una richiesta GET al seguente percorso, sostituendo il tuo ID account reale:

GET /api/v1/accounts/{account_id}/tickets

L'operazione si chiama listticketsby_account. Accetta due parametri:

• account_id — l'ID numerico dell'account (obbligatorio, parte del percorso URL)
• p — un dizionario opzionale di parametri di query aggiuntivi come paginazione o filtri

Una chiamata Python minimale si presenta così:

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

^[3]

Passo 4. Assicurati che il tuo client Desk abbia un orgId valido impostato.

Zoho Desk richiede un ID organizzazione (orgId) per ogni richiesta API. Se la tua integrazione non ha ancora memorizzato questo valore, il client può scoprirlo automaticamente chiamando l'endpoint delle organizzazioni al primo utilizzo. L'ID scoperto viene quindi salvato in modo che le chiamate successive — inclusa listticketsby_account — portino automaticamente l'intestazione corretta. ^[5][8]

Passo 5. Analizza e visualizza l'elenco dei ticket restituiti.

La risposta sarà un oggetto JSON contenente i record dei ticket per quell'account. I campi principali da mostrare agli utenti finali includono l'oggetto del ticket, lo stato, l'agente assegnato e la data di creazione. Ometti i campi ID interni in qualsiasi visualizzazione rivolta agli utenti per mantenere l'output leggibile. ^[6]

Passo 6. Costruisci un link diretto al portale per ogni ticket (opzionale).

Se vuoi fornire agli agenti un link cliccabile per ogni ticket, costruisci l'URL utilizzando il seguente schema:

https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}

Sostituisci {dc} con il suffisso del tuo data center (ad es., com, eu), {portal} con il nome del tuo portale o l'ID organizzazione, e {TicketId} con l'ID dalla risposta API. ^[4]

---

Errori comuni

• Intestazione orgId mancante. Se il client Desk viene inizializzato senza un ID organizzazione, tutte le richieste — incluse le ricerche di ticket per account — falliranno. Assicurati che il flusso di auto-discovery sia stato eseguito almeno una volta e che l'ID sia stato salvato. ^[5][8]
• Scope insufficienti. Per richiedere i ticket è necessario almeno Desk.tickets.READ. Se il tuo token è stato emesso solo con Desk.basic.READ, l'endpoint restituirà un errore di autorizzazione. Ri-autorizza con il set completo di scope. ^[2]
• Data center errato. L'URL base deve corrispondere al data center in cui è ospitato il tuo portale Zoho Desk. Utilizzare desk.zoho.com per un portale ospitato in EU non funzionerà; usa invece desk.zoho.eu. ^[4]

---

Cosa verificare

• Conferma che l'account_id nella tua richiesta corrisponda a un account esistente in Zoho Desk — un ID non corrispondente restituirà un risultato vuoto o un 404 anziché un errore che renda il problema evidente.
• Verifica che il token OAuth in uso abbia sia lo scope Desk.tickets.READ che Desk.contacts.READ prima di andare in produzione. ^[2]
• Dopo la prima chiamata riuscita, controlla che il deskorgid sia stato memorizzato nel tuo record di connessione in modo che le richieste future non debbano riscoprirlo. ^[8]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non è il supporto ufficiale Zoho. Per problemi a livello di piattaforma, apri sempre un ticket direttamente con Zoho.*