Come recuperare i record in Zoho CRM

L'API GraphQL di Zoho CRM ti consente di recuperare sia i dati dei record che i metadati dai tuoi moduli CRM in un'unica query flessibile — rendendola una potente alternativa alle tradizionali chiamate REST quando hai bisogno di attingere da più moduli contemporaneamente.

Perché è importante

Quando si creano integrazioni, dashboard o widget personalizzati, gli sviluppatori spesso hanno bisogno di recuperare dati da più moduli di Zoho CRM contemporaneamente. L'API GraphQL risponde a questa esigenza consentendo di combinare le query Records e Meta in un'unica richiesta, riducendo i round-trip e offrendoti un controllo preciso sui campi restituiti. ^[1] Questo è particolarmente utile per i team che creano strumenti di reportistica o sincronizzano i dati CRM con sistemi esterni.

Procedura passo dopo passo

Passo 1. Verifica che la tua edizione di Zoho CRM supporti GraphQL. L'API GraphQL non è disponibile nelle versioni di prova di nessuna edizione di Zoho CRM, quindi devi essere su un piano a pagamento prima di procedere. ^[1]

Passo 2. Autentica il tuo client API. Avrai bisogno di un token di accesso OAuth 2.0 valido con scope su Zoho CRM prima di inviare qualsiasi richiesta GraphQL. Una volta ottenuto il token, impostalo come token Bearer nell'intestazione Authorization della tua richiesta HTTP. ^[1]

Passo 3. Comprendi i due tipi di query radice disponibili. Lo schema GraphQL espone un tipo Query radice con due rami principali: ^[1]

• Records — recupera le righe di dati effettive da qualsiasi modulo CRM a cui il tuo profilo può accedere. Il filtraggio e la paginazione sono supportati in tutti i moduli.
• Meta — recupera dati strutturali/di configurazione da fonti come Modules, Users, KanbanView, UserProperties, ProfilePermissions, Profiles, Roles e Widgets. Alcuni di questi supportano anche il filtraggio e la paginazione.

Passo 4. Costruisci la tua query GraphQL. Di seguito è riportato un esempio che recupera AccountName dal modulo Accounts, LastName dai Leads, apiname dai Roles e lastname dagli Users — tutto in un'unica richiesta: ^[1]

query {
    Records {
        Accounts {
            _data {
                Account_Name {
                    value
                }
            }
        }
        Leads {
            _data {
                Last_Name {
                    value
                }
            }
        }
    }
    Meta {
        Roles {
            _data {
                api_name
            }
        }
        Users {
            _data {
                last_name
            }
        }
    }
}

Nota che i valori dei campi dei record sono accessibili tramite la chiave value annidata sotto il nome di ciascun campo, mentre alcuni campi di metadati (come api_name) sono accessibili direttamente. ^[1]

Passo 5. Invia la query all'endpoint GraphQL di Zoho CRM utilizzando il tuo client HTTP preferito (ad es., curl, Postman o un SDK lato server). Includi il tuo token OAuth nell'intestazione della richiesta e imposta il Content-Type su application/json. ^[1]

Passo 6. Analizza la risposta. L'API restituisce un oggetto JSON strutturato che rispecchia la forma della tua query. I record appaiono negli array _data all'interno di ciascun nodo modulo, e i campi dei metadati appaiono sotto i rispettivi nodi di tipo. ^[1]

Errori comuni

• Restrizione account di prova. Il tentativo di utilizzare l'API GraphQL su una versione di prova di Zoho CRM risulterà in un errore. Devi prima passare a un'edizione a pagamento. ^[1]
• Accesso basato sul profilo. La query Records mostra solo i moduli e i campi che il tuo profilo CRM ha il permesso di visualizzare. Se un modulo appare vuoto o manca dalla risposta, controlla le autorizzazioni a livello di campo e di modulo del tuo profilo in Zoho CRM. ^[1]
• Sensibilità alle maiuscole nei nomi dei campi. Le query GraphQL in Zoho CRM sono sensibili alle maiuscole. Ad esempio, LastName e lastname si riferiscono a campi diversi in contesti diversi (Records vs. Meta). Verifica attentamente i nomi API esatti dei tuoi campi prima di eseguire la query. ^[1]
• Paginazione per dataset di grandi dimensioni. Sebbene il filtraggio e la paginazione siano supportati per tutti i moduli Records e alcuni tipi Meta, omettere gli argomenti di paginazione su moduli di grandi dimensioni può comportare risposte troncate. Implementa sempre la paginazione quando esegui query su moduli con volumi elevati di record. ^[1]

Cosa verificare

• Edizione e stato di prova — verifica che la tua organizzazione sia su un piano Zoho CRM a pagamento, poiché GraphQL è bloccato sugli account di prova. ^[1]
• Scope del token OAuth — conferma che il tuo token di accesso includa gli scope CRM corretti; un token con scope insufficienti causerà errori di autenticazione anche se la sintassi della query è corretta. ^[1]
• Nomi API dei campi — confronta i nomi dei campi utilizzati nella tua query con i nomi API effettivi nella configurazione del tuo CRM (disponibili in Impostazioni → Moduli e Campi) per evitare risposte vuote o errate. ^[1]

---

*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non è il supporto ufficiale di Zoho. Per problemi a livello di piattaforma, verifica sempre con la documentazione ufficiale o i canali di supporto di Zoho.*