Come ottenere i campi in Zoho

Recuperare i campi in Zoho CRM richiede di chiamare il corretto endpoint API con un'autenticazione valida e il giusto contesto di modulo o layout — ecco come farlo in modo affidabile.

Perché è importante

Quando si creano integrazioni, automazioni o report personalizzati, è necessario sapere esattamente quali campi esistono in un determinato modulo o layout di Zoho CRM. Senza i nomi API corretti dei campi, le query e i filtri falliranno con errori di tipo "colonna non valida". Capire come recuperare i campi in modo programmatico aiuta inoltre a evitare di codificare in modo fisso i nomi dei campi, che potrebbero differire tra le organizzazioni.

Passo dopo passo

Passo 1. Assicurati che la connessione OAuth sia stabilita e che i token siano validi.

Prima di qualsiasi chiamata API, la tua integrazione deve disporre di un access token valido per l'organizzazione Zoho CRM di destinazione. La connessione è memorizzata insieme ai valori refreshtoken, accesstoken, apidomain e tokenexpires_at. Se l'access token è scaduto, un flusso di aggiornamento del token ne recupera automaticamente uno nuovo utilizzando il refresh token memorizzato, quindi salva il token aggiornato nel record di connessione. ^[3]

Passo 2. Identifica il data centre corretto per la tua organizzazione.

Zoho CRM è ospitato su più data centre. L'URL base per il CRM segue il pattern https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}, dove {dc} è il suffisso del data centre (ad esempio, com, eu, in, com.au). Il data centre viene tipicamente dedotto dall'api_domain restituito durante l'OAuth — in particolare dalla porzione successiva a zohoapis. in quella stringa di dominio. ^[1][5]

Passo 3. Determina se hai bisogno dei campi a livello di modulo o a livello di layout.

Zoho CRM distingue tra i campi associati all'intero modulo e i campi limitati a un layout specifico all'interno di quel modulo. Se hai bisogno di campi specifici per un layout, devi prima conoscere il layoutId del layout che stai prendendo di mira. Gli ID dei layout possono essere recuperati dall'endpoint dei layout prima di procedere alla chiamata dei campi.

Passo 4. Chiama l'endpoint dei campi per il layout pertinente.

Per recuperare i campi relativi a un particolare layout, invia una richiesta GET a /api/v1/layouts/{layoutId}/fields, sostituendo l'identificatore effettivo del layout. È possibile passare un dizionario di parametri di query opzionale (p) per filtrare o paginare i risultati. ^[4]

Un esempio Python minimale di questa chiamata è il seguente:

def get_layout_fields(self, layoutId: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/layouts/{layoutId}/fields", p, None)

^[4]

Passo 5. Verifica che gli scope OAuth necessari siano configurati.

Il token OAuth utilizzato deve includere gli scope appropriati per Zoho CRM. Gli scope necessari per un accesso CRM completo includono ZohoCRM.modules.ALL e ZohoCRM.org.ALL, tra gli altri. Senza questi scope, l'API restituirà un errore 401 o un errore di autorizzazione. ^[8]

Passo 6. Gestisci gli errori in modo appropriato.

Se l'API restituisce un messaggio "colonna non valida", significa in genere che il nome API del campo fornito in una query successiva non corrisponde a quanto restituito dall'endpoint dei campi. Se viene restituito uno stato 401, l'access token è stato rifiutato e l'utente dovrebbe riconnettere il proprio account Zoho. ^[6]

---

Errori comuni

• Data centre errato: Utilizzare crm.zoho.com quando la tua organizzazione si trova su crm.zoho.eu causerà errori di autenticazione o risposte vuote. Deriva sempre il data centre dall'api_domain memorizzato durante l'OAuth. ^[5]
• layoutId mancante: L'endpoint /api/v1/layouts/{layoutId}/fields richiede un identificatore di layout valido. Passare un ID vuoto o errato causerà il fallimento della richiesta. ^[4]
• Token scaduti: Se l'access token è scaduto e il flusso di aggiornamento fallisce (ad esempio perché il refresh token è stato revocato), l'istanza API restituirà None e nessun campo verrà recuperato. Verifica sempre che il refresher del token restituisca un access token valido prima di procedere. ^[3]
• Scope insufficienti: Se la concessione OAuth non includeva ZohoCRM.modules.ALL o equivalente, le chiamate di recupero dei campi verranno rifiutate. Rivedi gli scope configurati e ri-autorizza se necessario. ^[8]
• "Colonna non valida" nelle query successive: Dopo aver recuperato i campi, utilizza il nome API esatto (non l'etichetta visualizzata) quando costruisci filtri o query COQL. Una mancata corrispondenza genera un errore "nome colonna non valido". ^[6]

---

Cosa verificare

• Validità del token: Conferma che l'access_token memorizzato sia aggiornato e che il refresher del token possa ottenerne uno nuovo con successo se necessario. ^[3]
• ID layout corretto: Verifica che il layoutId che stai passando a /api/v1/layouts/{layoutId}/fields corrisponda a un layout effettivo nel modulo di destinazione. ^[4]
• Copertura degli scope: Controlla che la tua concessione OAuth includa ZohoCRM.modules.ALL (o lo scope minimo richiesto) affinché l'endpoint dei campi sia accessibile. ^[8]

---

*Beam Help fornisce supporto esperto indipendente per Zoho — non siamo il supporto ufficiale Zoho. Per problemi a livello di piattaforma, fai sempre riferimento alla documentazione ufficiale dell'API di Zoho CRM.*