> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.

# PIT GHL — collegare il GHL del cliente alla dashboard

> Procedura operativa: prendere il PIT (Private Integration Token) dalla location GHL cliente e collegarlo alla dashboard Mattone, così il cliente vede i lead della sua landing direttamente in app.mattone.co.

Ogni volta che attivi Marketing per un nuovo cliente, dopo aver setuppato snapshot + form + landing, l'ultimo passo è **collegare il suo GHL alla dashboard Mattone**. Da quel momento il cliente vede i propri lead in `app.mattone.co` senza doversi loggare su GHL.

## Perché serve

* Il cliente non sa usare GHL (interfaccia complessa)
* Il cliente vuole vedere lead + statistiche marketing dentro un'unica dashboard (Mattone)
* Facilita il follow-up e la conversione dei lead dal team del cliente
* Ci permette di aggregare metriche di marketing (CPL, CR, revenue attribution) lato Mattone

## Cosa serve prima di iniziare

* [ ] Sub-account del cliente creato dallo snapshot «Mattone V2» ✅
* [ ] Form GHL "Landing - Valutazione Immobile" creato ✅
* [ ] Landing Vercel già deployata (`nomeagenzia.vercel.app`) ✅
* [ ] Cliente ha completato registrazione su `app.mattone.co` e ha accesso alla sua area

Se manca qualcosa vedi [Setup landing agenzia — GHL](/integrazioni/ghl/setup-agenzia-landing) per rimediare prima.

## Procedura passo-passo

<Steps>
  <Step title="1. Crea il PIT sulla location del cliente">
    Entri nella location GHL del cliente → **Settings** (icona ingranaggio in basso a sinistra) → **My Staff** → tab **Private Integrations** (in alto a destra) → **+ Create New Integration**.

    Compila così:

    * **Name**: `Mattone Dashboard`
    * **Scopes** (spunta minimo questi):
      * `contacts.readonly`
      * `contacts.write`
      * `opportunities.readonly`
      * `locations.readonly`
      * `calendars.readonly` (se vuoi mostrare anche i booking sulla dashboard)

    Click **Create**. Appare il token una sola volta — **copialo subito** in un blocco note temporaneo, non si può rileggere dopo.

    <Warning>
      Se dimentichi di copiare il token e chiudi la modale, devi cancellare il PIT e crearne un altro. Non ci sono API per rileggerlo.
    </Warning>
  </Step>

  <Step title="2. Copia il Location ID">
    Sempre nella location cliente → **Settings** → **Business Profile** → in alto trovi **Location ID** (formato `LKB1XXXXXXXXXXXXXX` o simile).

    Copialo insieme al token.

    <Note>
      In alternativa il Location ID è visibile nell'URL della location: `https://app.gohighlevel.com/v2/location/LKB1XXXXXXXXXXXXXX/...`
    </Note>
  </Step>

  <Step title="3. Fai loggare il cliente su Mattone">
    Il cliente accede a **app.mattone.co** con le sue credenziali (le stesse mail/password che ha ricevuto quando è stato attivato).

    Se non ricorda la password: `Password dimenticata?` sulla schermata login → arriva mail di reset via Resend.
  </Step>

  <Step title="4. Vai su /connessioni (o Marketing → Integrazione GHL)">
    Nell'area cliente Mattone:

    * Sidebar → **Connessioni** (o **Marketing** → tab **Integrazione GHL**)
    * Cerca la **card GoHighLevel**
    * Click **"Collega GHL"** (o **"Modifica"** se era già collegato)
  </Step>

  <Step title="5. Incolla PIT + Location ID">
    Nella modale che si apre:

    * **Token (PIT)**: incolla il token del passo 1
    * **Location ID**: incolla il Location ID del passo 2
    * Click **Salva**

    Mattone testa immediatamente la connessione:

    * Se **verde ✅** → connessione ok, il cliente vede lead in dashboard
    * Se **rosso ❌** con errore → vedi §"Troubleshooting" sotto
  </Step>

  <Step title="6. Verifica lato cliente">
    * Sidebar Mattone → **Acquisizione** (o **Marketing**)
    * Se ci sono lead in pipeline GHL del cliente, appaiono qui
    * Se pipeline è vuota, invia un lead di test (compila la landing con dati tuoi) e verifica che appaia in \~30 sec
  </Step>
</Steps>

## Cosa il cliente vede dopo il collegamento

Nella sua area `app.mattone.co`:

* **Sezione Marketing**: KPI (lead ricevuti, tasso conversione, source Facebook/Google/organic)
* **Lista lead**: nome, telefono, indirizzo immobile, stage pipeline
* **Notifiche in tempo reale** ogni nuovo lead (email/push)
* **Tempo risparmiato AI** e **valore aggregato**

Tutto senza dover mai aprire GHL.

## Chi può fare cosa

<Note>
  **Chi fa il setup marketing NON può collegare il PIT per conto del cliente** dal proprio account. L'endpoint `/api/integrations/ghl` è student-scoped: usa l'auth della sessione utente e salva su `pms_integrations` con `student_id = user.id`.

  **Come si fa**: una call con il cliente in condivisione schermo. Gli passi i valori PIT + Location ID (li hai già presi al passo 1-2) e li incolla lui in `/connessioni`. È rapido e il cliente impara dove sta la sua integrazione.

  **Non si usano le credenziali del cliente per fare il collegamento al posto suo.** Se il cliente non è raggiungibile, si aspetta o si chiede al team Mattone: la procedura è nel repo interno.
</Note>

## Troubleshooting

<Warning>
  **Errore "Credenziali non valide" al salvataggio** → Il token è probabilmente stato copiato incompleto (spesso GHL ci mette uno spazio o troncatura). Rifai copy dal PIT o crea un nuovo PIT.
</Warning>

<Warning>
  **Errore "Location non trovata"** → Location ID errato. Controlla di aver preso quello dalla location del cliente e non dal profilo agency GHL.
</Warning>

<Warning>
  **Lead della landing non appaiono in dashboard** → Verifica che il form GHL scriva davvero nella pipeline di acquisizione del cliente (quella nata da **CRM \[Nome Agenzia]**), stadio **🔵 Nuovo Lead** (Actions on submit → Add to pipeline), e che in **Connessioni → GoHighLevel → Pipeline di acquisizione** sia in uso proprio quella pipeline. Se il form scrive in un'altra pipeline, i lead esistono ma la piattaforma non li conta. Sugli studenti connessi con il vecchio snapshot (Cosmica CRM) la pipeline ereditata può chiamarsi ancora «Crm Cosmica Italia Affitti Brevi»: vedi [Studenti già connessi con il vecchio snapshot](/integrazioni/ghl/setup-agenzia-landing#studenti-gia-connessi-con-il-vecchio-snapshot-cosmica-crm).
</Warning>

<Warning>
  **Scope insufficienti (401 su alcuni endpoint)** → Se hai creato il PIT senza tutti gli scope elencati sopra, **cancellalo** e creane uno nuovo con gli scope corretti. Gli scope non si possono modificare dopo la creazione.
</Warning>

## Tempo stimato

* Passo 1-2 (PIT + Location ID): 3 min
* Passo 3-5 (cliente si logga + incolla): 5 min (con call condivisa)
* Passo 6 (verifica lead): 2 min

**Totale**: \~10 min con cliente al telefono.

## Riferimenti

* [Setup landing agenzia — GHL](/integrazioni/ghl/setup-agenzia-landing) — la procedura completa (snapshot, form, PIT, landing, redirect)
* [Procedura marketing end-to-end](/delivery/marketing-onboarding) — le 7 fasi dall'onboarding cliente al primo lead
* [PIT + Location GHL](/integrazioni/ghl/pit-location) — dettaglio scope, token lifecycle, sicurezza


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.