Come recuperare un singolo record in Zoho

Recuperare un singolo record in Zoho CRM tramite API significa puntare a una voce specifica tramite il suo ID univoco, restituendo solo i dati necessari senza dover scaricare un intero elenco.

Perché è importante

Quando si costruiscono integrazioni o automazioni, recuperare un elenco completo di record solo per leggerne uno è dispendioso e lento. Individuare un record tramite ID mantiene le chiamate API snelle, evita di raggiungere i limiti di frequenza e rende i flussi di lavoro basati su Deluge o REST molto più facili da mantenere. Questo schema è particolarmente comune quando un trigger (come un workflow o un webhook) fornisce già un ID record e occorre semplicemente arricchire o validare i dati di quel record.

> Nota: Beam Help è un servizio di supporto esperto indipendente per Zoho — non siamo il supporto ufficiale Zoho.

---

Procedura passo dopo passo

Passaggio 1. Ottieni un token di accesso OAuth valido per Zoho CRM.

Prima di qualsiasi chiamata API, il client deve scambiare le proprie credenziali con un bearer token. Il token viene passato nell'intestazione di ogni richiesta come Authorization: Zoho-oauthtoken <your_token>. Senza di esso, l'API CRM rifiuterà la richiesta. ^[3]

Passaggio 2. Identifica il modulo e l'ID del record che vuoi recuperare.

Zoho CRM organizza i dati in moduli come Leads, Contacts, Accounts, Deals e così via. Ogni record all'interno di un modulo ha un id numerico univoco (ad esempio, 3652397000009851001). È necessario conoscere sia il nome del modulo sia l'ID del record prima di effettuare la chiamata. ^[3]

Passaggio 3. Costruisci la richiesta GET all'endpoint del singolo record.

L'API Zoho CRM v8 espone i record individuali all'indirizzo:

GET https://www.zohoapis.com/crm/v8/{Module}/{record_id}

Sostituisci {Module} con il nome API del modulo (es. Leads, Contacts) e {record_id} con l'ID numerico del Passaggio 2. Un esempio minimale con curl è il seguente:

curl "https://www.zohoapis.com/crm/v8/Leads/3652397000009851001" \
  -X GET \
  -H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

^[3]

Passaggio 4. Facoltativamente, limita i campi restituiti usando il parametro di query fields.

Per ridurre le dimensioni del payload, aggiungi ?fields= seguito da un elenco di nomi di campo API separati da virgola. Ad esempio, per recuperare solo il cognome e l'indirizzo email di un lead:

GET /crm/v8/Leads/3652397000009851001?fields=Last_Name,Email

Questo rispecchia lo stesso parametro fields utilizzato nelle chiamate a elenco e mantiene la risposta compatta. ^[3]

Passaggio 5. Analizza la risposta.

Una chiamata riuscita restituisce un array data contenente un singolo oggetto. Estrai i campi necessari direttamente da quell'oggetto. Ad esempio, in una risposta JSON si accede a data[0].Last_Name o data[0].Email. L'id del record è sempre presente nella risposta indipendentemente dai campi richiesti. ^[3]

Passaggio 6. Gestisci il record all'interno di Deluge (se usi workflow o funzioni di Zoho CRM).

Se stai chiamando l'API dall'interno di uno script Deluge anziché da un sistema esterno, usa il task invokeurl con lo stesso endpoint e intestazione OAuth. Memorizza la risposta analizzata in una variabile mappa, quindi usa .get("fieldapiname") per estrarre i singoli valori — lo stesso schema utilizzato quando si lavora con le API di altri prodotti Zoho. ^[2]

---

Errori comuni

• Nome API del modulo errato. Il nome del modulo nell'URL deve corrispondere esattamente al nome API del CRM, incluse le maiuscole (es. Leads e non leads). Una discrepanza restituisce un errore 404 o INVALID_MODULE. ^[3]
• Token OAuth scaduto o mancante. I token hanno una durata limitata. Se ricevi una risposta 401 INVALID_TOKEN, aggiorna il token di accesso prima di riprovare. ^[3]
• Richiesta di un lead convertito senza il flag converted. Quando si recuperano lead già convertiti, l'endpoint standard potrebbe non restituirli a meno che non si includa esplicitamente ?converted=true nelle chiamate a elenco. Per le ricerche di singoli record, verifica che il record esista ancora nel modulo che stai interrogando. ^[3]
• Confusione nei formati degli ID record. Gli ID in Zoho CRM sono lunghe stringhe numeriche. Passare un ID troncato o digitato in modo errato produrrà un errore di record non trovato. Copia sempre l'ID in modo programmatico anziché manualmente. ^[3]

---

Cosa verificare

• Conferma che l'array data della risposta contenga esattamente un oggetto — se è vuoto, l'ID record non esiste in quel modulo oppure il token non dispone dello scope necessario.
• Verifica i nomi API dei campi nelle impostazioni dei campi del modulo CRM e assicurati che corrispondano a quelli passati nel parametro fields; i nomi visualizzati e i nomi API spesso differiscono.
• Controlla che il tuo scope OAuth includa ZohoCRM.modules.READ (o l'equivalente specifico del modulo) affinché il token sia autorizzato a leggere i record del modulo di destinazione. ^[3]