Beam Help
Richiedi supporto

How-to · Zoho CRM

Come ottenere le pipeline in Zoho

Recupera tutte le pipeline disponibili nella tua istanza Zoho.

Recuperare le pipeline in Zoho CRM è semplice una volta stabilita la connessione OAuth — puoi interrogare l'API dei moduli CRM per estrarre i dati delle pipeline (fasi delle trattative) direttamente dal tuo account.


Perché è importante


I team di vendita si affidano alle pipeline per monitorare le trattative attraverso ogni fase del funnel. Se stai costruendo un'integrazione, automatizzando i report o utilizzando uno strumento come Zoho AI Pilot Engine di Beam Help, dovrai recuperare i dati delle pipeline e dei moduli in modo programmatico. Comprendere gli scope corretti e il flusso API garantisce dati accurati e in tempo reale, anziché snapshot obsoleti.


Procedura passo dopo passo


Passaggio 1. Configura le tue credenziali API Zoho visitando la Zoho API Console e creando un'Applicazione Server-based. Annota il tuo Client ID e il Client Secret — ti serviranno entrambi per autenticare qualsiasi richiesta API.[1]


Passaggio 2. Durante la registrazione dell'applicazione, assicurati di includere lo scope ZohoCRM.modules.ALL insieme a ZohoCRM.settings.ALL e ZohoCRM.users.ALL. Lo scope dei moduli è ciò che consente l'accesso ai dati delle pipeline e delle fasi delle trattative all'interno di Zoho CRM.[1]


Passaggio 3. Imposta il tuo redirect URI in modo che corrisponda esattamente a quello registrato nella API Console. Se stai lavorando in locale, di solito è http://localhost:8080/api/auth_callback. Una discrepanza causerà un errore di redirect OAuth e bloccherà lo scambio del token.[1]


Passaggio 4. Archivia le tue credenziali in modo sicuro in un file .env nella root del progetto. Le variabili minime richieste sono ZOHOCLIENTID, ZOHOCLIENTSECRET e l'impostazione del data center (ZOHO_DC), che per impostazione predefinita è com ma può essere impostata su eu, in, com.au o jp a seconda di dove è ospitato il tuo account Zoho.[1]


Passaggio 5. Stabilisci la connessione OAuth. Una volta avviato il server, fai clic su Connect Zoho CRM nell'interfaccia utente e completa il flusso di autorizzazione. Il sistema memorizza il tuo access token e il refresh token in modo che le richieste successive vengano gestite automaticamente.[2]


Passaggio 6. Il livello di connessione aggiorna automaticamente il tuo access token quando mancano meno di 120 secondi alla scadenza, in modo che le query sulle pipeline a lunga esecuzione non falliscano a metà richiesta con un errore 401. Questo viene gestito in modo trasparente — non è necessario gestire manualmente la rotazione dei token.[6]


Passaggio 7. Per recuperare i dati delle pipeline, esegui una query in linguaggio naturale come *"mostrami tutte le trattative"* o *"elenca le opportunità aperte"*. Internamente questo si traduce in una chiamata search_records al modulo Deals, che contiene le fasi della pipeline per ogni record.[7]


Passaggio 8. Se vuoi un conteggio dei record per ogni fase della pipeline, puoi chiedere *"quante trattative ho"* — questo viene instradato allo strumento getrecordcount con il modulo Deals come parametro, fornendo una rapida indicazione del volume della pipeline.[7]


Passaggio 9. Per i link diretti ai record, il pattern URL del CRM segue https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. Sostituisci il codice del tuo data center e il nome del modulo pertinente (ad es. Deals) per creare link profondi verso specifici record della pipeline.[5]


Errori comuni


  • Redirect URI errato. Il redirect URI nel tuo .env e nella Zoho API Console deve essere identico carattere per carattere. Anche una differenza nella barra finale causerà il fallimento del callback OAuth.[1]
  • Scope del modulo mancante. Omettere ZohoCRM.modules.ALL dall'elenco degli scope significa che gli endpoint delle pipeline e delle fasi delle trattative restituiranno errori di autorizzazione. Includi sempre tutti e tre gli scope consigliati durante la registrazione dell'app.[1]
  • Data center errato. Se il tuo account Zoho si trova nel data center EU o India e ZOHODC è lasciato su com, le chiamate API raggiungeranno l'endpoint sbagliato e restituiranno errori di autenticazione. Imposta ZOHODC in modo che corrisponda alla regione del tuo account.[1]
  • Stato del database obsoleto. Se riscontri errori imprevisti dopo aver modificato le credenziali o ri-autorizzato, eliminare il file SQLite locale (data/zpilot.sqlite) e riavviare il server forza uno stato pulito.[2]

Cosa verificare


  • Conferma che ZohoCRM.modules.ALL e ZohoCRM.settings.ALL siano entrambi elencati tra gli scope approvati della tua applicazione nella Zoho API Console.[1]
  • Verifica che ZOHO_DC nel tuo .env corrisponda al data center mostrato nell'URL del tuo account Zoho CRM (ad es. eu per crm.zoho.eu).[1]
  • Dopo la connessione, testa il percorso di aggiornamento del token attendendo uno stato di prossima scadenza o verificando che la tabella zohoconnections venga aggiornata con un nuovo accesstoken e tokenexpiresat.[6]

---


*Beam Help è un servizio di supporto esperto indipendente per Zoho — non siamo il supporto ufficiale Zoho e questa guida si basa sulla nostra esperienza di implementazione diretta.*

Sources cited

  1. [1] README.md
  2. [2] run_llm_routing_suite.py
  3. [3] build_extensions.py
  4. [4] server.py: build_zoho_links
  5. [5] server.py: get_zoho_connection
  6. [6] server.py: chat_stream
  7. [7] planner.py
Ottenere le Pipeline in Zoho | Beam Help — Beam Help