Come recuperare le note in Zoho CRM

Il recupero delle note in Zoho CRM può essere effettuato tramite l'interfaccia utente sui singoli record oppure in modo programmatico attraverso le REST API di Zoho CRM, a seconda del caso d'uso. Qui su Beam Help — supporto esperto indipendente per Zoho, non supporto ufficiale Zoho — ti guidiamo attraverso entrambi gli approcci.

Perché è importante

Le note sono uno degli strumenti più pratici per tracciare l'avanzamento di una trattativa o di un'interazione con il cliente, offrendo a ogni membro del team un riepilogo aggiornato di quanto è accaduto su un record. ^[2] Che tu abbia bisogno di estrarre note per reportistica, audit o per visualizzarle in un widget personalizzato, conoscere il metodo di recupero corretto fa risparmiare molto tempo. Se stai costruendo un'integrazione o un'automazione, è particolarmente importante comprendere correttamente il percorso via API.

Procedura passo dopo passo

Passaggio 1. Capire cosa sono le Note in Zoho CRM.

Le note fungono da livello di riepilogo sopra i record CRM, consentendo ai rappresentanti commerciali di documentare osservazioni sulle interazioni con clienti e prospect, in modo che l'avanzamento delle trattative sia sempre visibile al team. ^[8] Possono essere associate a moduli standard come Lead, Contatti, Account e Trattative.

Passaggio 2. Recuperare le note tramite l'interfaccia utente di Zoho CRM.

Apri qualsiasi record in Zoho CRM (ad esempio, un Contatto o un Account). Scorri verso il basso fino alla sezione degli elenchi correlati nella pagina di dettaglio del record, dove una scheda o un pannello Note mostrerà tutte le note associate a quel record. ^[1] Puoi fare clic su qualsiasi nota singola per leggerne il contenuto completo.

Passaggio 3. Utilizzare l'endpoint API Notes per recuperare le note in modo programmatico.

Zoho CRM espone un modulo Notes dedicato tramite le sue REST API. Per recuperare le note, chiama l'endpoint standard Get Records puntando al modulo Notes:

GET https://www.zohoapis.com/crm/v8/Notes

Includi il tuo token OAuth nell'intestazione Authorization come Zoho-oauthtoken <your_token>. ^[6]

Passaggio 4. Autenticarsi con lo scope OAuth corretto.

Il recupero del modulo Notes richiede accesso a livello di amministratore. Se un utente non amministratore tenta di chiamare l'endpoint del modulo Notes, l'API restituisce un errore HTTP 403 NOT_SUPPORTED, indicando che solo gli utenti amministratori sono autorizzati a recuperare record dal modulo Notes. ^[6] Assicurati che il token OAuth che stai utilizzando appartenga a un utente amministratore o sia generato per conto di esso.

Passaggio 5. Gestire la paginazione con page_token per set di risultati di grandi dimensioni.

Quando il numero di note è elevato, la risposta dell'API includerà un valore page_token. Passa questo token come parametro di query nella richiesta successiva per recuperare la pagina seguente di risultati. ^[6] Ad esempio:

GET https://www.zohoapis.com/crm/v8/Notes?page_token=<token_value>

Continua a iterare finché non viene restituito alcun ulteriore page_token, il che segnala che hai raggiunto l'ultima pagina.

Passaggio 6. Filtrare le note per record padre se necessario.

Se vuoi solo le note appartenenti a un record specifico (ad esempio, un determinato Lead o Contatto), utilizza l'API COQL per scrivere una query mirata sul modulo Notes, filtrando per l'ID del record padre. ^[2] Questo evita di estrarre tutte le note dall'intero CRM e mantiene efficienti le tue chiamate API.

Passaggio 7. Visualizzare le note tramite l'estensione Zoho FSM (se applicabile).

Se la tua organizzazione utilizza l'estensione Zoho FSM all'interno di Zoho Desk, le note sui record CRM collegati possono essere visualizzate anche lì. Naviga su un record Contatto o Account, fai clic sulla scheda Zoho FSM, passa il cursore su una Richiesta, Preventivo, Ordine di Lavoro, Appuntamento di Servizio o Asset collegato, e fai clic sull'icona Visualizza Note. Verrai portato direttamente alla scheda Note per quel record. ^[1]

Errori comuni

• Errore 403 NOT_SUPPORTED: È il problema più comune durante il recupero delle note via API. Si verifica quando il token OAuth in uso non appartiene a un utente amministratore. Verifica il ruolo dell'utente e rigenera il token con credenziali di amministratore. ^[6]
• Note visibili su desktop ma non su mobile/tablet: Esistono inconsistenze di visualizzazione note per cui gli elenchi correlati Note e Allegati vengono visualizzati correttamente nel browser desktop ma potrebbero non essere renderizzati come previsto nelle versioni tablet o mobile di Zoho CRM. ^[5] Se il tuo team fa affidamento sull'accesso mobile, testa la visibilità delle Note su ogni tipo di dispositivo.
• Paginazione non gestita: Se effettui una sola chiamata API senza verificare la presenza di un page_token nella risposta, potresti perdere silenziosamente una grande parte dei tuoi dati di note. Controlla sempre i metadati della risposta per i token di paginazione. ^[6]

Cosa verificare

• Conferma che il token OAuth utilizzato per le chiamate API appartenga a un utente amministratore, poiché i token non amministratori verranno rifiutati con un errore 403 quando si interroga il modulo Notes. ^[6]
• Verifica che l'elenco correlato Note sia abilitato e visibile nel layout del modulo per i record che stai ispezionando nell'interfaccia utente. ^[5]
• Se utilizzi la paginazione, assicurati che il tuo codice scorra tutti i valori page_token fino al raggiungimento della pagina finale, in modo che nessuna nota venga omessa dai risultati. ^[6]