Come eseguire ricerche in tutti i moduli di Zoho Desk

La ricerca in tutti i moduli di Zoho Desk viene effettuata tramite un unico endpoint API che interroga ticket, contatti, account, attività e altro in una sola chiamata — a condizione che il token OAuth includa lo scope di ricerca corretto.

Perché è importante

Quando gli agenti di supporto o le integrazioni devono individuare un record senza sapere in quale modulo si trova, una ricerca modulo per modulo è lenta e soggetta a errori. Zoho Desk espone un'operazione di ricerca trasversale dedicata, che consente di recuperare i record corrispondenti da ogni area rilevante dell'helpdesk in un unico round-trip. Questo è particolarmente utile nei flussi di lavoro automatizzati, nei chatbot o nei portali personalizzati costruiti sull'API di Zoho Desk.

Procedura passo dopo passo

Passaggio 1. Verifica che la tua applicazione OAuth includa lo scope Desk.search.READ. Senza di esso, l'endpoint di ricerca restituirà un errore di autorizzazione. Questo scope si affianca agli altri scope di Desk come Desk.tickets.READ, Desk.contacts.READ e Desk.articles.READ — tutti potenzialmente necessari a seconda dei moduli da cui vuoi ottenere risultati. ^[1]

Passaggio 2. Richiedi (o aggiorna) un token di accesso OAuth che includa Desk.search.READ tra gli scope concessi. Se stai creando un'integrazione multi-app che coinvolge anche Zoho CRM, combina gli scope di Desk con quelli di CRM in un'unica richiesta di autorizzazione, così da utilizzare un solo token. ^[1][3]

Passaggio 3. Invia una richiesta HTTP GET all'endpoint API di Zoho Desk /api/v1/search, passando i parametri di query nella richiesta. L'operazione è identificata internamente come searchacrossmodules. ^[2]

GET https://desk.zoho.com/api/v1/search
Authorization: Zoho-oauthtoken <your_access_token>

Passaggio 4. Fornisci il termine di ricerca e gli eventuali filtri opzionali come parametri della query string (rappresentati come dizionario p nel wrapper API). Come minimo, di solito si passa un parametro word o searchStr contenente il testo da cercare. ^[2]

Passaggio 5. Analizza la risposta JSON. I risultati sono raggruppati per modulo, quindi il codice deve iterare sulle chiavi dell'oggetto restituito (ad es. tickets, contacts, accounts) per presentare i record rilevanti all'utente o al sistema a valle. ^[2]

Passaggio 6. Se stai integrando questa funzionalità in un assistente conversazionale o in un'interfaccia di chat, lo strumento può essere invocato dinamicamente quando un utente pone una domanda che fa riferimento ai propri dati Desk. Il livello dell'assistente chiama searchacrossmodules e poi formatta i risultati in una risposta leggibile dall'utente. ^[4][7]

Errori comuni

• Scope mancante al momento della generazione del token. Lo scope Desk.search.READ deve essere presente quando il token OAuth viene *creato per la prima volta*. Aggiungerlo alla configurazione in un secondo momento non ha effetto finché l'utente non ri-autorizza. Verifica attentamente l'elenco degli scope prima di andare in produzione. ^[1][3]

• URL base del data center errato. Zoho Desk è ospitato su più data center (com, eu, in, com.au, ecc.). Assicurati che l'URL base utilizzato corrisponda al data center in cui è stato creato il portale, altrimenti riceverai un reindirizzamento o un errore 404. ^[7]

• Conflitti di scope nelle integrazioni combinate. Se la tua applicazione si connette anche a Zoho CRM, la stringa degli scope combinati deve essere costruita con attenzione — gli scope di Desk e quelli di CRM vengono concatenati insieme. Un errore di formattazione (ad es. una virgola mancante o uno spazio finale) può eliminare silenziosamente degli scope dal token. ^[1][3]

• Errori API visualizzati come errori dello strumento. Se Zoho rifiuta la richiesta (ad esempio a causa di un token scaduto o di un parametro non valido), la risposta conterrà un campo error anziché i risultati. Implementa una logica di gestione degli errori che rilevi questa situazione e richieda all'utente di riprovare con parametri corretti. ^[6]

Cosa verificare

• Lo scope è presente nel token attivo — decodifica il token di accesso o ispeziona il grant OAuth per confermare che Desk.search.READ compaia nell'elenco degli scope prima di effettuare la prima chiamata. ^[1]
• Il percorso dell'endpoint e l'URL del data center sono corretti — verifica che l'URL base corrisponda al data center del portale e che il percorso sia esattamente /api/v1/search. ^[2][7]
• La risposta contiene risultati per i moduli attesi — esegui una query di test per un record noto e conferma che il modulo atteso (ad es. tickets o contacts) compaia nel payload della risposta. ^[2]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non rappresenta il supporto ufficiale Zoho. Fai sempre riferimento alla documentazione ufficiale dell'API di Zoho Desk per le specifiche più aggiornate su scope ed endpoint.*