Come recuperare le metriche dei ticket in Zoho Desk

Le metriche dei ticket in Zoho Desk sono disponibili tramite un singolo endpoint REST che restituisce i dati di performance per qualsiasi ticket individuale — senza dover navigare nella dashboard.

Perché è importante

Quando hai bisogno di verificare i tempi di risposta, misurare la conformità agli SLA o estrarre dati di performance grezzi in una pipeline di reportistica, l'API di Zoho Desk ti offre accesso programmatico diretto alle metriche per singolo ticket. Questo è particolarmente utile per i team che costruiscono dashboard personalizzate o automatizzano i controlli di qualità senza dover navigare manualmente nell'interfaccia agente di Desk.

Procedura passo dopo passo

Passaggio 1. Verifica che il tuo token OAuth includa gli scope Desk corretti prima di effettuare qualsiasi chiamata API. Come minimo hai bisogno di Desk.tickets.READ nel tuo elenco di scope autorizzati — opzioni più ampie come Desk.tickets.ALL soddisfano anch'esse questo requisito. ^[3]

Passaggio 2. Identifica il ticket_id numerico del ticket di cui vuoi le metriche. Puoi trovarlo nell'URL del portale agente di Zoho Desk, che segue il pattern https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}, oppure interrogando prima l'endpoint dell'elenco ticket. ^[4]

Passaggio 3. Invia una richiesta GET all'endpoint delle metriche, sostituendo l'ID del tuo ticket nel percorso:

GET /api/v1/tickets/{ticket_id}/metrics

L'endpoint accetta ticket_id come parametro di percorso obbligatorio e un parametro opzionale p per eventuali opzioni di query aggiuntive che desideri passare. ^[1]

Passaggio 4. In Python, la chiamata si presenta così utilizzando il wrapper ZohoDeskApi:

metrics = api.get_ticket_metrics(ticket_id="12345")

Passa un dizionario opzionale come secondo argomento (p) se hai bisogno di includere parametri di query aggiuntivi. ^[1]

Passaggio 5. Analizza il dizionario di risposta restituito. Il nostro team consiglia di stampare o registrare la risposta completa durante lo sviluppo, in modo da poter vedere esattamente quali campi metrici restituisce la tua organizzazione Desk — la disponibilità dei campi può variare in base al piano e alla configurazione. ^[5]

Passaggio 6. Se stai costruendo un flusso di lavoro conversazionale o automatizzato, il pattern dell'assistente Zoho Desk prevede di chiamare sempre lo strumento con dati reali anziché ipotizzare i valori. Verifica di avere il ticket_id prima di invocare l'endpoint; se manca, richiedilo esplicitamente prima di procedere. ^[5]

Errori comuni

• Scope OAuth mancanti o errati. Se il tuo token è stato generato senza Desk.tickets.READ (o Desk.tickets.ALL), l'API restituirà un errore di autorizzazione. Controlla attentamente la stringa degli scope nella tua configurazione OAuth — ogni scope deve essere separato da una virgola senza spazi finali. ^[3]

• Token di accesso scaduti. I token di accesso Zoho scadono (tipicamente dopo un'ora). Il livello API dovrebbe aggiornarsi automaticamente utilizzando il refreshtoken memorizzato; se riscontri errori 401, verifica che la logica di aggiornamento del token stia scrivendo il nuovo accesstoken nel tuo archivio di connessione prima di riprovare. ^[8]

• Dominio del data center errato. Desk è ospitato su più data center regionali. L'URL base cambia in base al tuo DC — ad esempio https://desk.zoho.com per gli account .com rispetto a https://desk.zoho.{dc} per le regioni EU, IN, AU e altre. Utilizzare il dominio sbagliato causerà errori di connessione o errori 404. ^[4]

• Org ID non impostato. Il ZohoDeskClient richiede un'intestazione orgid valida per ogni richiesta. Se il tuo record di connessione non ha ancora deskorg_id popolato, il client tenterà di individuarlo automaticamente chiamando l'endpoint delle organizzazioni al primo utilizzo. Assicurati che questo passaggio di individuazione venga completato con successo prima di chiamare l'endpoint delle metriche. ^[8]

Cosa verificare

• Verifica che la risposta contenga i campi metrici attesi (ad es. tempo di risposta, tempo di risoluzione) e che nessuno sia null a causa del ticket ancora aperto o non assegnato.
• Conferma che i tuoi scope OAuth includano almeno Desk.tickets.READ e che il token sia stato aggiornato se ha più di un'ora. ^[3]
• Incrocia il ticket_id restituito con l'URL del portale agente di Desk per assicurarti di aver interrogato il ticket corretto. ^[4]

---

*Beam Help fornisce una guida esperta indipendente per i prodotti Zoho e non è il supporto ufficiale Zoho.*