Come recuperare la cronologia dei ticket in Zoho Desk

Il recupero della cronologia dei ticket in Zoho Desk avviene tramite un endpoint API dedicato che restituisce un registro cronologico di tutte le modifiche apportate a un determinato ticket. Qui su Beam Help — supporto esperto indipendente per Zoho (non supporto ufficiale Zoho) — ti guidiamo passo dopo passo su come effettuare la chiamata e cosa preparare prima di iniziare.

Perché è importante

Quando un ticket di supporto passa attraverso più agenti, cambiamenti di stato o aggiornamenti di priorità, hai bisogno di un audit trail affidabile per capire cosa è successo e quando. L'endpoint della cronologia del ticket ti fornisce quel registro completo in modo programmatico, rendendolo utile per reportistica, verifiche di conformità o debug di stati imprevisti del ticket. Se stai costruendo un'integrazione o un'automazione su Zoho Desk, questo è spesso uno dei primi dati che vorrai esporre.

Procedura passo dopo passo

Passo 1. Verifica che gli scope OAuth siano configurati correttamente.

Prima di effettuare qualsiasi chiamata API, l'applicazione connessa deve disporre delle autorizzazioni corrette. Per la cronologia dei ticket in particolare, è necessario almeno lo scope Desk.tickets.READ autorizzato sul tuo client OAuth. Un accesso più ampio può essere concesso con Desk.tickets.ALL, che copre le operazioni di lettura, scrittura, creazione, aggiornamento ed eliminazione sui ticket. ^[2]

Passo 2. Ottieni un access token valido.

La tua integrazione si autentica tramite OAuth 2.0. Se il tuo access token attuale è scaduto, devi rinnovarlo inviando una richiesta POST all'endpoint token di Zoho con clientid, clientsecret e refreshtoken usando granttype: refreshtoken. Una risposta positiva restituisce un nuovo accesstoken insieme a un valore expiresin (tipicamente 3600 secondi) che dovresti memorizzare insieme a un timestamp calcolato tokenexpires_at per sapere quando rinnovarlo. ^[8]

Passo 3. Identifica l'ID della tua organizzazione (org_id).

Le chiamate API di Zoho Desk richiedono un header orgId per instradare le richieste al portale corretto. Se non lo hai ancora memorizzato, puoi scoprirlo chiamando l'endpoint delle organizzazioni e leggendo il campo id dal primo elemento nell'array data restituito. Una volta recuperato, salvalo in modo da non doverlo cercare ad ogni richiesta. ^[4]

Passo 4. Chiama l'endpoint della cronologia del ticket.

Invia una richiesta GET autenticata al seguente percorso, sostituendo l'identificatore reale del ticket:

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

Il nome dell'operazione per questa chiamata è gettickethistory. Passi il ticket_id come parametro di percorso. Un parametro opzionale p può essere fornito come dizionario di query per scopi di paginazione o filtraggio. ^[3]

Un esempio minimo in Python è il seguente:

# Assuming `client` is an initialised ZohoDeskClient
history = client.request("GET", f"/api/v1/tickets/{ticket_id}/history", p, None)

Dove p è None oppure un dizionario di parametri di query aggiuntivi. ^[3]

Passo 5. Naviga al ticket nell'interfaccia di Zoho Desk (verifica opzionale).

Se vuoi confrontare la risposta API con quanto visibile nel browser, il pattern URL diretto per la pagina di dettaglio di un ticket segue questa struttura:

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

Sostituisci {dc} con il suffisso del tuo data center (ad es. com, eu, in), {portal} con il nome del tuo portale o l'ID dell'organizzazione, e {ticket_id} con l'identificatore numerico del ticket. ^[7]

Errori comuni

• orgId mancante o errato: Se org_id è vuoto o errato, l'API non riuscirà a instradare la richiesta al portale Desk corretto. Verifica sempre che sia memorizzato e non vuoto prima di effettuare chiamate sui ticket. ^[4]
• Scope OAuth insufficienti: Richiedere la cronologia con soli scope di scrittura o creazione comporterà un errore di autorizzazione. Assicurati che Desk.tickets.READ o Desk.tickets.ALL sia esplicitamente incluso nella stringa degli scope. ^[2]
• Access token scaduto: I token scadono dopo circa un'ora. Se ricevi un errore di autenticazione, controlla il valore tokenexpiresat e avvia un rinnovo prima di riprovare. ^[8]
• Dominio del data center errato: Zoho opera su più data center regionali. Se il tuo account si trova sul data center EU o IN, l'URL base dell'API e l'URL del token OAuth devono utilizzare il suffisso regionale corrispondente, non il dominio predefinito .com. ^[7]

Cosa verificare

• Conferma che Desk.tickets.READ (o Desk.tickets.ALL) compaia nell'elenco degli scope OAuth autorizzati prima di effettuare la chiamata. ^[2]
• Verifica che un accesstoken valido e non scaduto e un deskorg_id non vuoto siano entrambi presenti nel record di connessione prima di chiamare l'endpoint della cronologia. ^[4]
• Confronta almeno una voce della cronologia dalla risposta API con il registro delle attività del ticket nell'interfaccia agente di Zoho Desk per confermare che i dati vengano restituiti correttamente. ^[7]