Troubleshooting GHL: PIT, dati mancanti e scope errati

Usa questa pagina per diagnosticare i problemi dell’integrazione GHL. I problemi più comuni sono due: un PIT scaduto o eliminato accidentalmente da GHL, e dati di lead mancanti a causa di scope errati al momento della creazione del token. Prima di escalare, verifica sempre lo stato del PIT in GHL Settings, risolve la maggior parte dei casi.

Due numeri WhatsApp diversi, non confonderli. Il numero WhatsApp collegato a GHL in questa pagina serve a contattare lead e proprietari (marketing/acquisizione). Il numero WhatsApp che risponde agli ospiti è tutta un’altra cosa: è la WABA di Conduit, vedi Telefonia e WABA. Se la domanda parla di ospiti, non è questa pagina.

Tabella di diagnosi

Sintomo	Causa probabile	Soluzione
Dati lead non si aggiornano	PIT scaduto o eliminato da GHL	Vai in GHL → Settings → Private Integrations e verifica che l’integrazione “Mattone Platform” sia ancora attiva; se è stata eliminata, rigenera il PIT seguendo la procedura completa
Marketing mostra 0 lead (o pochi) ma nel CRM ce ne sono	La piattaforma sta leggendo un’altra pipeline con gli stessi stadi. Capita soprattutto agli studenti connessi con il vecchio snapshot (Cosmica CRM): hanno due pipeline di acquisizione, quella ereditata Crm Cosmica Italia Affitti Brevi e la loro	1. In Marketing guarda quale pipeline nomina la riga Numeri calcolati sulla pipeline…. 2. Apri Connessioni → GoHighLevel → Pipeline di acquisizione e scegli manualmente quella con le opportunità dello studente (disponibile dal 15/09/2026). 3. In GHL rinomina o cancella la pipeline ereditata, se ha 0 opportunità. 4. Ricarica Marketing e verifica che i numeri corrispondano al CRM. Dettagli in Collegamento
Avviso “rinomina la pipeline” in Marketing	L’unica pipeline di acquisizione del sub-account ha ancora un nome che contiene “Cosmica”	Se è la pipeline che lo studente usa, rinominala in GHL con il nome della sua attività (es. CRM [Nome Agenzia]). Se i suoi lead stanno altrove, crea la sua pipeline con gli stessi stadi (parole chiave incluse) e poi sceglila in Connessioni
Marketing non riconosce una pipeline rinominata dallo studente	Nel rinominare gli stadi è andata persa la parola chiave che la piattaforma cerca (es. “Nuovo Lead” → “New lead” o “Da chiamare”)	Verifica ogni stadio contro la tabella parola-chiave in Setup landing agenzia — GHL e rimetti la parola chiave (il resto del nome è libero)
Avviso “la pipeline che avevi scelto non c’è più”	La pipeline scelta in Connessioni è stata cancellata in GHL, oppure gli stadi sono stati rinominati e non ricalcano più il Mattone 1	La piattaforma sta usando la scelta automatica. Apri Connessioni → GoHighLevel e scegli di nuovo
ROAS mostra 0 o N/A	Opportunity value non compilato nel CRM GHL dello studente	Chiedi allo studente di verificare che tutte le opportunità in pipeline abbiano un valore numerico compilato in GHL; senza questo campo il calcolo del ROAS non è possibile
Campagna non attribuita	Campaign ID mancante sul contatto GHL, il tracking UTM non è configurato correttamente	Verifica nell’account GHL dello studente che l’integrazione campagne sia attiva e che i parametri UTM siano configurati sulle landing page e negli annunci
Rebilling non parte	Attivazione manuale non eseguita a fine mese 2	Attiva manualmente il rebilling nell’account agenzia GHL per il sub-account dello studente; consulta la pagina Rebilling per i dettagli
Scopes insufficienti (403)	PIT creato con scope errati o incompleti al momento della generazione	Elimina il PIT attuale in GHL Settings e rigenera una nuova integrazione con gli scope corretti: Contacts Read, Opportunities Read, Campaigns Read; contatta il team tecnico per aggiornare la configurazione del token nella piattaforma
I campi custom del modulo Meta non compaiono sull’opportunità	Non è un errore: i campi custom del modulo lead Meta non si collegano ai dettagli dell’opportunità in GHL	Si leggono in Contatti → domande Meta, non sulla scheda dell’opportunità. Il lead sta nel contatto
Il lead ha email al posto di nome/cognome, o manca il telefono	Disallineamento nella mappatura fra i campi del modulo Meta e i campi del contatto in GHL	Verifica la mappatura del modulo lead: corregge chi segue GHL per lo studente, non è un problema del singolo lead
Il numero WhatsApp delle campagne si blocca a ogni messaggio inviato	Il numero è stato installato nell’app WhatsApp normale sul telefono, oltre che collegato a GHL	Non va mai installato nell’app: il numero delle campagne si usa solo collegato (da PC, a GHL/Conduit). Se è già compromesso serve un numero nuovo, mai usato altrove
Verifica del Business Manager bloccata o account in revisione	Causa più frequente: dati fiscali incoerenti (ragione sociale o P.IVA nel BM diversi da quelli dichiarati), o mancanti	Verifica che i dati fiscali nel Business Manager corrispondano esattamente a quelli reali dello studente; segnala a chi segue il marketing se la verifica resta bloccata oltre qualche giorno

Per verificare rapidamente se il PIT di uno studente è ancora valido senza aspettare un errore in produzione, vai in GHL → Settings → Private Integrations e controlla che l’integrazione denominata “Mattone Platform” sia presente e attiva. Se lo stato mostra “Active”, il token è operativo. Se la voce è assente, il token è stato eliminato e va rigenerato prima del prossimo ciclo di aggiornamento dati.

Verificare un nuovo Refresh dello snapshot (per il team)

Prima di dare per buono un Refresh di «Mattone V2» dal sub-account Sandbox, chi lavora in GHL fa passare il template dallo script di audit del repo niccolosanso-ops/Dashboard-Mattone (scripts/ghl-snapshot-audit.mjs, branch claude/ghl-snapshot-mattone-m94ljy, PR #6).

1. Prepara le variabili

Lo script legge quattro variabili d’ambiente: il PIT di agenzia (GHL_AGENCY_PIT), l’ID della company/agenzia (GHL_COMPANY_ID), l’ID della location Sandbox (GHL_SANDBOX_LOCATION_ID) e il PIT della location Sandbox (GHL_LOCATION_PIT). Serve il PIT della location Sandbox, non solo quello di agenzia: un PIT di agenzia non può entrare in un sub-account perché non può avere lo scope oauth.write.

Qui si scrivono solo i nomi delle variabili, mai i valori: il contenuto di questo repository viene pubblicato su docs.mattone.co, quindi non deve mai contenere token o ID reali (vedi CONTRIBUTING.md).

2. Esegui lo script

Lancia scripts/ghl-snapshot-audit.mjs con le variabili impostate nell’ambiente. Lo script legge i nomi degli asset via API GHL.

3. Verifica 0 residui

Si procede al push/refresh dello snapshot solo con 0 residui dei nomi di clienti e modelli usati in passato per costruire il CRM (la lista esatta è nello script, non si scrive qui — questo repository è pubblico, vedi CONTRIBUTING.md).

4. Controlla a mano quello che l'API non vede

Via API si vedono solo i nomi degli asset. Il contenuto di workflow ed email/SMS e le funnel page vanno aperti e letti a mano: lo script non li controlla.

Non esiste ancora una pagina interna dedicata al team in questo repository (è interamente pubblico): finché non ce n’è una, questa procedura resta qui, nel troubleshooting GHL.

▷ Prompt Claude Code: Debug GHL · incolla in Claude Code:

Contesto: in questa sessione di Claude Code NON hai il repo/codice caricato.
Per prima cosa apri i repo giusti, `~/Projects/mattone-platform` (KPI marketing/
lead) e `~/Projects/ghl-mcp` (client GHL), e LEGGI le pagine mattone-docs
/troubleshooting/metodo e /integrazioni/ghl/troubleshooting; per i dati veri usa
l'MCP GHL. Poi procedi:

Applica il metodo di mattone-docs /troubleshooting/metodo a questo problema GHL:
[DESCRIVI IL SINTOMO, es. "KPI marketing vuoti" / "valore lead a zero"]. Leggi
i dati reali prima di concludere: verifica che il PIT della location sia valido
(header Authorization Bearer + Version 2021-07-28) e che le opportunità abbiano
un valore. Isola: PIT mancante/scaduto? spesa non inserita dal CSM? valore
opportunità assente in GHL? Proponi il fix (rigenera PIT / inserisci spesa /
valorizza le opportunità) e dimmi come verificarlo.

PIT & location

Rigenera il token

Lead & valore

Cosa legge la piattaforma

PMS & CRM

Reconciliation (banca)

Conduit AI

Numeri & WhatsApp (WABA)

Dati & Revenue

Pagamenti & Vendita diretta

Smart Lock

Troubleshooting GHL: PIT, dati mancanti e scope errati

Tabella di diagnosi

Verificare un nuovo Refresh dello snapshot (per il team)

PIT & location

Lead & valore

​Tabella di diagnosi

​Verificare un nuovo Refresh dello snapshot (per il team)

PIT & location

Lead & valore

Tabella di diagnosi

Verificare un nuovo Refresh dello snapshot (per il team)