Come ottenere i record di una vista in Zoho Desk

Recuperare i record da una vista specifica in Zoho Desk è semplice una volta che si dispone dell'ID vista corretto e degli scope OAuth appropriati. Ecco tutto ciò che devi sapere per ottenere i record di una vista tramite l'API di Zoho Desk.

Perché è importante

Zoho Desk organizza ticket, contatti e altre entità in viste — filtri salvati che raggruppano i record in base a criteri come stato, assegnatario o priorità. Se vuoi recuperare programmaticamente i record appartenenti a una di queste viste (per reportistica, automazione o integrazione), devi chiamare l'endpoint dedicato ai record della vista anziché un endpoint di elenco generico. Questo è utile anche quando vuoi replicare ciò che un agente vede nella propria coda di Desk all'interno di uno strumento o dashboard di terze parti.

Procedura passo dopo passo

Passaggio 1. Verifica che gli scope OAuth includano l'accesso in lettura a Desk.

Prima di effettuare qualsiasi chiamata API, verifica che il token OAuth di Zoho Desk connesso sia stato concesso almeno con Desk.tickets.READ (o lo scope del modulo pertinente, come Desk.contacts.READ). Un'integrazione completa include in genere anche Desk.basic.READ affinché l'API possa risolvere i metadati dell'organizzazione e del dipartimento. Senza gli scope corretti, la richiesta restituirà un errore di autorizzazione. ^[2]

Passaggio 2. Recupera il tuo ID organizzazione.

Ogni chiamata all'API di Zoho Desk deve essere associata a un'organizzazione. Se non hai ancora memorizzato l'orgId, chiama prima l'endpoint delle organizzazioni. Scorri l'array data restituito, prendi il campo id dal primo elemento e salvalo per il riutilizzo. Una volta individuato, passa questo valore come intestazione orgId in tutte le richieste successive. ^[4][6]

Passaggio 3. Identifica l'ID della vista di destinazione.

Accedi a Zoho Desk nel browser, apri la vista che vuoi interrogare e annota l'ID numerico nell'URL — oppure recuperalo programmaticamente dall'endpoint dell'elenco delle viste. Passerai questo valore come parametro di percorso view_id nel passaggio successivo. ^[3]

Passaggio 4. Chiama GET /api/v1/views/{view_id}/records.

Invia una richiesta GET autenticata all'endpoint seguente, sostituendo il tuo ID vista effettivo:

GET /api/v1/views/{view_id}/records

Il nome dell'operazione è getviewrecords. I parametri supportati sono:

| Parametro | Descrizione |

|-----------|-------------|

| view_id | L'ID numerico della vista (parametro di percorso) |

| p | Dizionario opzionale di paginazione o filtro passato come parametri di query |

Una chiamata Python minimale si presenta così:

result = desk_api.get_view_records(view_id="123456", p={"limit": 50})

Il client invia la richiesta GET e restituisce la risposta JSON analizzata contenente i record corrispondenti. ^[3]

Passaggio 5. (Facoltativo) Recupera solo il conteggio dei record.

Se hai bisogno solo di sapere quanti record esistono in una vista — ad esempio per mostrare un contatore badge o decidere se paginare — usa la variante count dello stesso endpoint:

GET /api/v1/views/{view_id}/records/count

L'operazione è getviewrecordscount e accetta gli stessi parametri viewid e p. ^[7]

Passaggio 6. Costruisci link diretti ai record restituiti.

Once you have the response, puoi costruire URL navigabili nel browser per ciascun record. Per i ticket il pattern è:

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

Per contatti e account, il percorso base segue rispettivamente {deskrecordsroot}/contacts o {deskrecordsroot}/accounts. Se non è disponibile uno slug del portale, al suo posto viene utilizzato l'ID organizzazione. ^[1][5]

Errori comuni

• Intestazione orgId mancante. Zoho Desk richiede l'ID organizzazione in ogni richiesta. Se l'deskorgid memorizzato è vuoto o non aggiornato, l'API rifiuterà le chiamate. Il pattern di auto-discovery (recupero delle organizzazioni al primo utilizzo e salvataggio del risultato) previene questo tipo di errore silenzioso. ^[4][6]
• Combinazioni di scope errate. Richiedere Desk.tickets.ALL non copre automaticamente contatti o attività. Ogni modulo necessita del proprio scope (Desk.contacts.READ, Desk.tasks.READ, ecc.). Verifica l'elenco completo degli scope se ricevi errori 403 su specifici tipi di record. ^[2]
• Mancata corrispondenza del data center. Zoho ospita i dati in più regioni (.com, .eu, .in, ecc.). Assicurati che l'URL base corrisponda al data center in cui è stato creato l'account — ad es. https://desk.zoho.eu per gli account EU — altrimenti le richieste falliranno o verranno reindirizzate in modo imprevisto. ^[5]

Cosa verificare

• Gli scope sono presenti e attivi — conferma che Desk.tickets.READ (e qualsiasi altro scope di modulo necessario) compaia nell'elenco degli scope concessi al token prima di andare in produzione. ^[2]
• Il view_id è valido per la tua organizzazione — gli ID vista sono specifici dell'organizzazione; un ID vista di un portale Zoho Desk non funzionerà in un altro. ^[3]
• La paginazione è gestita — se il parametro p supporta un limit o un offset di pagina, verifica che il tuo codice scorra tutte le pagine in modo che nessun record venga perso silenziosamente. ^[3][7]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non è il supporto ufficiale Zoho. Per problemi di fatturazione o a livello di account, contatta direttamente Zoho.*