Come recuperare i layout in Zoho CRM

Il recupero dei layout in Zoho CRM avviene principalmente tramite l'API di Zoho CRM, che consente di ottenere i metadati dei layout — incluse le disposizioni dei campi e le strutture delle sezioni — per qualsiasi modulo del tuo account. Qui su Beam Help (supporto esperto indipendente per Zoho, non supporto ufficiale Zoho), ti guidiamo attraverso i principali approcci di seguito.

Perché è importante

Quando si creano integrazioni, interfacce utente personalizzate o automazioni, è spesso necessario sapere esattamente come è strutturato il layout di pagina di un modulo prima di poter visualizzare o validare correttamente i dati. I layout definiscono quali campi compaiono, in quale ordine e in quali sezioni — quindi recuperarli in modo programmatico è un passaggio fondamentale per qualsiasi progetto di sviluppo serio su Zoho CRM. Questo è rilevante anche quando si desidera verificare le differenze di layout tra i profili o sincronizzare le modifiche ai layout con un sistema esterno. ^[3]

---

Procedura passo dopo passo

Passaggio 1. Verifica che la tua edizione di Zoho CRM supporti l'accesso alle API. Le API GraphQL, ad esempio, non sono disponibili nelle versioni di prova di nessuna edizione di Zoho CRM, quindi assicurati che il tuo account sia su un piano a pagamento prima di tentare il recupero dei metadati. ^[3]

Passaggio 2. Decidi quale superficie API si adatta al tuo caso d'uso. Zoho CRM offre sia endpoint in stile REST che un'API GraphQL. L'API GraphQL è particolarmente adatta per il recupero di layout e metadati perché espone un tipo radice Meta dedicato che copre moduli, utenti, profili, ruoli e metadati correlati in un'unica query. ^[3]

Passaggio 3. Autentica la tua applicazione tramite OAuth 2.0 per ottenere un token di accesso valido. Tutte le chiamate all'API di Zoho CRM richiedono un bearer token con scope appropriati per le autorizzazioni CRM. Consulta la documentazione per sviluppatori di Zoho CRM per gli scope OAuth corretti per l'accesso ai metadati.

Passaggio 4. Per recuperare i metadati dei layout tramite l'API GraphQL, invia una query che punta al tipo Meta. Il tipo Meta supporta il recupero da Modules, Users, KanbanView, UserProperties, ProfilePermissions, Profiles, Roles e Widgets. Alcuni di questi tipi supportano anche il filtraggio e la paginazione, utile quando hai bisogno dei layout solo per un modulo specifico. ^[3]

Una query GraphQL minimale che punta ai metadati del modulo è la seguente:

query {
  Meta {
    Modules {
      _data {
        api_name
      }
    }
  }
}

Estendi il blocco _data con i campi specifici del layout richiesti dalla tua integrazione (come ID layout, nome o profili associati). ^[3]

Passaggio 5. Se stai lavorando all'interno di un widget basato su browser o un'applicazione lato client, considera l'utilizzo dell'SDK JavaScript di Zoho CRM anziché chiamate HTTP dirette. L'SDK fornisce un modo strutturato per effettuare chiamate API dal contesto dell'interfaccia utente di Zoho CRM, e il codice di esempio per il recupero dei dati dei moduli è disponibile nel repository GitHub dell'SDK. ^[5]

Passaggio 6. Una volta recuperati i dati del layout, confrontali con quanto visualizzato nell'interfaccia di Zoho CRM navigando su Impostazioni → Moduli e Campi. Questa è la stessa area in cui viene gestita la personalizzazione di moduli e layout, e costituisce un utile controllo di coerenza per verificare che la risposta dell'API corrisponda alla configurazione attiva. ^{[1] [2]}

Passaggio 7. Se il tuo progetto prevede layout basati su Canvas (viste dettaglio record personalizzate), tieni presente che Canvas ora supporta le viste anche per le pagine di creazione dei record, oltre alle viste dettaglio. Le viste Canvas possono anche essere esportate e importate tra account CRM tramite una chiave univoca, valida per un periodo limitato. Se hai bisogno di replicare i layout tra organizzazioni, questo meccanismo di esportazione/importazione può integrare il tuo flusso di lavoro di recupero basato su API. ^[8]

---

Errori comuni

• Restrizioni degli account di prova. Il tentativo di eseguire query sui metadati GraphQL su un account Zoho CRM di prova fallirà. Passa a un'edizione a pagamento prima di effettuare i test. ^[3]
• Scope non corrispondenti. Se il tuo token OAuth non dispone dello scope corretto per i metadati CRM, l'API restituirà un errore di autorizzazione anziché i dati del layout. Verifica sempre che gli scope del token corrispondano all'endpoint che stai chiamando.
• Confusione tra GraphQL e REST. Il tipo Meta e i suoi sotto-tipi (incluso Modules) sono specifici dell'API GraphQL. Se stai utilizzando l'API REST, la struttura degli endpoint e il formato della risposta differiscono significativamente. Confondere i due è una fonte comune di errori inaspettati. ^[3]
• I layout Canvas sono separati. I layout di pagina standard e le viste Canvas sono costrutti distinti in Zoho CRM. I metadati API per il layout standard di un modulo non includeranno automaticamente i dettagli del template Canvas. ^[8]

---

Cosa verificare

• Verifica che la risposta dell'API includa i valori api_name del modulo attesi e che corrispondano ai nomi dei moduli visibili in Impostazioni → Moduli e Campi nel tuo account CRM. ^{[1] [3]}
• Assicurati che la paginazione sia gestita se il tuo CRM ha un numero elevato di moduli o layout — il tipo Meta di GraphQL supporta la paginazione per alcuni sotto-tipi, e le risposte troncate sono un errore silenzioso comune. ^[3]
• Testa con l'SDK JavaScript se la tua integrazione viene eseguita all'interno di un widget di Zoho CRM, per garantire che venga utilizzato il contesto di autenticazione corretto anziché un token OAuth gestito manualmente. ^[5]