Categoria
Mappatura campi
A cosa serve la mappatura dei campi?
Ogni sorgente che invia dati (webhook, automazione, integrazione) usa nomi propri per i suoi valori. La mappatura dei campi dice al sistema quale valore ricevuto corrisponde a quale campo interno: ID Bitrix, ADS, campagna, telefono, lista, prodotto, pipeline, regione, provincia, data di arrivo.
Senza mappatura il dato arriva ma resta in attesa, perché il sistema non sa dove metterlo.
Quali campi sono obbligatori?
ID Bitrix, ADS, campagna e telefono sono contrassegnati con un asterisco rosso: se mancano, il lead non può essere collegato al cliente e resta tra i lead in attesa.
Come collego un campo?
Apri Amministrazione, sezione Mappatura campi, scegli la sorgente e usa il menu di ricerca accanto al campo. Il menu mostra tutti i percorsi presenti nell'ultimo dato ricevuto insieme al valore trovato, così puoi verificare subito di aver scelto quello giusto.
Puoi anche scrivere un percorso a mano e confermare con Invio.
Cosa fa il pulsante di prova?
Applica la mappatura al dato di esempio e mostra il risultato: che valore finisce in ogni campo e quali campi obbligatori restano vuoti (in rosso). Dopo il salvataggio la prova viene rieseguita automaticamente, quindi la lista si aggiorna da sola.
Cosa significa "In revisione"?
Finché la revisione è attiva i dati in arrivo vengono messi da parte e non entrano nella dashboard: serve mentre stai sistemando la mappatura.
Importante: con la revisione attiva il pulsante "Riprocessa" non funziona. Prima disattiva la revisione, poi riprocessa i dati in attesa.
Posso cambiare i nomi dei campi mostrati?
Sì. Ogni campo ha un nome tecnico e un nome visualizzato. Puoi personalizzare il nome visualizzato per sorgente; vengono salvate solo le personalizzazioni, il resto segue i nomi standard.
Categoria
Mappatura campagne
Come si collega una campagna a un cliente?
In Amministrazione, sezione Mappatura campagne, ogni nome campagna in arrivo può essere assegnato a un cliente e, se serve, a un'area specifica. Le stesse assegnazioni si possono fare direttamente dalla dashboard, dalla coda delle campagne non ancora assegnate.
Che differenza c'è tra Area, Italia e Ignora?
Area: i lead della campagna vengono conteggiati nella zona indicata.
Italia: i lead restano sul cliente ma senza zona presidiata, con dettaglio a parte.
Ignora: la campagna non viene conteggiata (utile per test o traffico non pertinente).
Perché non riesco a salvare una campagna?
Se il lead è arrivato senza nome campagna non c'è nulla da assegnare: nella coda compare la scritta rossa "Senza nome campagna".
In quel caso collega il campo campagna nella Mappatura campi della sorgente interessata e poi riprocessa i lead in attesa.
Categoria
Mappatura liste
Cosa fa la mappatura delle liste?
Collega i valori di lista che arrivano da Bitrix alle categorie di reparto usate nella dashboard. È la mappatura che decide cosa appare nella sezione "Lead effettivi ricevuti".
Perché una lista non compare nella dashboard?
In "Lead effettivi ricevuti" vengono mostrate solo le liste già assegnate al cliente. Se una lista non è stata mappata, non viene visualizzata: assegnala nella sezione Mappatura liste.
Posso decidere l'ordine con cui vedo le liste?
Sì. Ogni lista può avere un numero d'ordine: i numeri positivi vengono mostrati prima, le liste senza numero dopo. È disponibile anche l'opzione "Riga vuota dopo" per separare visivamente i gruppi.
L'ordine è una preferenza di visualizzazione salvata sul dispositivo, non modifica i dati.
Categoria
Mappatura spesa
Come viene attribuita la spesa pubblicitaria?
La spesa in arrivo viene collegata al cliente nella sezione Mappatura spesa, in modo indipendente dalla mappatura dei lead: una campagna può contare i lead su un cliente e la spesa su un altro se necessario.
Che differenza c'è tra spesa automatica e manuale?
Automatica: la spesa arriva dalle piattaforme e viene conteggiata così com'è.
Manuale: la spesa automatica del cliente viene esclusa e inserisci tu l'importo giornaliero (sono gestibili gli ultimi 30 giorni).
Se torni in automatico, gli importi manuali restano nello storico ma non vengono più conteggiati.
Cosa vuol dire "spesa non assegnata"?
Sono importi arrivati con un nome campagna che non è collegato a nessun cliente. Finché resta così non entra nel costo per lead: assegnala nella Mappatura spesa.
Categoria
Aree e zone
Come funzionano aree e zone?
Ogni cliente può avere più aree geografiche, e ogni area contiene le province presidiate ed eventuali parole chiave di riconoscimento. Servono a capire dove è stato generato il lead.
Il conteggio per zona segue il nome della campagna?
No. Il conteggio per zona segue la geografia reale del lead (regione e provincia), non il nome della campagna.
I lead che ricadono in regioni non presidiate vengono raccolti sotto "Italia" con il dettaglio delle regioni.
Categoria
Lead in pending
Cosa sono i lead in pending?
Sono i dati arrivati che il sistema non ha potuto abbinare a un lead esistente o a una mappatura completa. Restano in attesa da oltre un'ora e vengono segnalati con un avviso in alto.
Quali sono le cause più frequenti?
Un campo obbligatorio non è mappato (tipicamente campagna o ID Bitrix).
L'identificativo inviato non corrisponde a un contatto reale: deve contenere solo il numero dell'ID, senza prefissi o secondi identificativi attaccati.
La sorgente è in revisione, quindi i dati restano volutamente in attesa.
Come si sistema un lead in attesa?
Correggi la causa (mappatura, nome campagna, identificativo inviato), poi riprocessa i dati in attesa dalla sezione Mappatura campi. Le righe vecchie non più utili possono essere ignorate.
A cosa serve "ignora" e cosa sono le regole?
Ignorare una riga la toglie dagli avvisi senza cancellare nulla; l'elenco degli ignorati resta consultabile in fondo alla pagina e si può ripristinare.
Le regole permettono di ignorare automaticamente casi ricorrenti, per campo e valore oppure per testo contenuto (senza distinzione tra maiuscole e minuscole). Una regola può valere per tutti i clienti o solo per uno.
Gli ignorati sono condivisi: valgono per tutti i dispositivi.
Perché vedo un avviso di un cliente che non sto guardando?
L'avviso segue il cliente selezionato: se compare qualcosa di un altro cliente, controlla quale cliente è attivo nel filtro in alto. Nella pagina dei lead pendenti la colonna Cliente indica a chi è assegnata ogni riga o se non è assegnata.
Categoria
Filtri della dashboard
Come funzionano i filtri in alto?
Il filtro cliente decide tutti i numeri della pagina: una sola azienda per volta. Il filtro data definisce il periodo e per impostazione predefinita mostra gli ultimi 7 giorni, oggi incluso.
Il cliente selezionato resta memorizzato e viene mostrato in tutte le pagine.
Cosa fa il pulsante Aggiorna?
Ricarica i dati dal database e mostra l'orario dell'ultimo aggiornamento. Per evitare richieste inutili resta disabilitato per circa un minuto dopo ogni uso.
Cosa significano i numeri principali?
Doppioni iniziali: percentuale di duplicati sui dati in ingresso.
Doppioni dopo le attivazioni: percentuale di duplicati sui lead lavorati.
Lead attivati: quanti lead sono stati effettivamente attivati.
Costo per lead e spesa totale: derivano dalla spesa attribuita al cliente nel periodo scelto.
Categoria
Clienti
Cos'è un cliente nel sistema?
È l'azienda di cui si misurano i lead. Ogni cliente ha nome, identificativo breve, aree/zone, campagne, liste e spesa collegate. Tutta la dashboard si legge un cliente per volta.
Come si crea o si modifica un cliente?
In Amministrazione, sezione Clienti. Un nuovo cliente si può creare anche al volo mentre assegni una campagna. Dopo la creazione conviene configurare aree/zone, liste e modalità di spesa.
Perché esistono clienti tecnici?
Alcune voci servono solo al funzionamento interno (ad esempio la raccolta dei dati non ancora assegnati o gli importi inseriti a mano) e non sono clienti reali: per questo non compaiono nei filtri.
Categoria
Utenti e accessi
Quanti modi di accesso esistono?
Due. L'accesso riservato con codice unico del sito, che apre tutto compresa l'amministrazione. E l'accesso dipendenti con email e password, limitato ai clienti assegnati.
Cosa vede un dipendente?
Solo i clienti che gli sono stati assegnati, e senza i dati di spesa. Se non ha nessun cliente assegnato l'accesso viene rifiutato.
Come si abilita una persona?
L'account va creato nell'area autenticazione del database, poi in Amministrazione, sezione Accessi dipendenti, lo colleghi a uno o più clienti oppure lo rendi amministratore.
Quanto dura la sessione?
L'accesso dipendenti resta valido 7 giorni, poi va rifatto. In alto sono sempre visibili email e ruolo di chi sta usando la pagina, con il pulsante per uscire.
Categoria
Database e workflow n8n
Come funziona il database e i workflow n8n (panoramica tecnica completa)
Questa dashboard conta e attribuisce i lead che arrivano da Bitrix24 e da Facebook. Sotto ci sono tre pezzi che lavorano insieme.
Architettura in breve
- Supabase (database Postgres) è il backend e l'unica fonte di verità: qui vivono i lead, i clienti, le campagne, la spesa e tutte le regole.
- Questa dashboard (il frontend) legge da Supabase e mostra conteggi, filtri e sezioni di amministrazione. Non calcola nulla di suo: mostra ciò che il database ha già elaborato.
- n8n è l'orchestratore: riceve i dati in tempo reale da Bitrix24/Facebook (webhook) e li inoltra a Supabase.
Il percorso di un lead è sempre: Bitrix24 o Facebook → webhook → n8n → funzione su Supabase → tabella dei lead → viste lette da questa dashboard.
Il principio "un cliente = una sorgente = un token"
Ogni cliente ha la sua sorgente dedicata (in "Mappatura campi") con un token univoco, usato in tutti i suoi workflow n8n. Il token identifica da chi arriva il dato. Anche due clienti con dati identici vanno tenuti su sorgenti separate: mescolarli renderebbe impossibile attribuire correttamente lead e segnali.
Come entra un lead (pipeline di ingest)
Quando arriva un evento, n8n chiama la funzione ingest passando il token della sorgente e il payload grezzo. Supabase registra l'evento e lo elabora nella stessa transazione: legge la "Mappatura campi" della sorgente per capire dove trovare campagna, telefono, provincia, ID, ecc., e crea/aggiorna il lead. La mappatura ammette più percorsi alternativi per lo stesso campo: viene usato il primo valore non vuoto (così una sola mappatura copre più formati di payload).
Le tabelle principali
- Lead: un record per coppia (cliente, ID Bitrix). L'ID Bitrix è la chiave univoca del lead, non per forza un ID reale di Bitrix.
- Clienti: anagrafica dei clienti, più un cliente tecnico "Da assegnare" che raccoglie ciò che non è ancora attribuito.
- Registro campagne: associa ogni campagna a un cliente per i LEAD. L'attribuzione è retroattiva: appena assegni una campagna a un cliente (in "Mappatura campagne"), tutti i lead di quella campagna passano al cliente giusto.
- Registro spesa campagne + spesa giornaliera: associa le campagne ai clienti per la SPESA pubblicitaria e conserva la spesa per giorno/piattaforma. Da qui nascono CPL e costi.
- Sorgenti/Mappatura, segnali pendenti, regole di ignoro, mappatura liste: gestiscono l'ingest, i segnali in attesa e cosa nascondere.
Stati del lead e doppioni
Un lead può essere valido, doppione o attivato. Lo stato non si "mappa" dal payload: viene impostato da una chiamata dedicata (segnala_stato). Un doppione è un contatto già presente in Bitrix: viene comunque registrato e marcato come doppione, così lo vedi nei conteggi senza sovrascrivere il lead originale.
Attribuzione e "Da assegnare"
Finché una campagna non è assegnata a un cliente, i suoi lead (e la sua spesa) restano sul cliente tecnico "Da assegnare". Assegnando la campagna in "Mappatura campagne" (lead) e in "Mappatura spesa" (spesa) tutto si sposta sul cliente reale, in automatico e retroattivo.
Spesa ignorata
Se una campagna di spesa viene lasciata su "Da assegnare", viene marcata come "ignorata" e la sua spesa finisce in un parcheggio separato, così non sporca i totali dei clienti. Se poi la assegni a un cliente vero, la spesa rientra automaticamente sotto quel cliente.
Pulizia automatica
Alcune regole automatiche (trigger) puliscono ogni lead in ingresso: il telefono viene ridotto alle sole cifre e i campi di testo vengono ripuliti da spazi e a-capo ai bordi. Vale per tutti i flussi, presenti e futuri: non serve pulire nei nodi n8n.
I workflow n8n
Ogni cliente ha il suo workflow, ma la logica è comune. Esempio completo, il workflow Facebook di Nocera ("FB_InnovazioneGreen FTV Balcone OK"):
Webhook (Facebook) -> Controllo CAP -> Normalizza telefono -> Sanifica email -> If (email valida?)
- se email NON valida -> Send email (avviso di errore a chi gestisce, con nome/telefono/email del lead)
- se email valida -> Ricerca telefono su Bitrix -> If (il contatto esiste gia?)
- NO (lead nuovo) -> Crea contatto su Bitrix -> `ingest` (registra il lead nuovo)
- SI (doppione) -> Aggiorna contatto -> Get contatto -> `ingest` (registra il doppione) -> `segnala_stato` (marca "doppione")
Perché i doppioni usano un ID "sintetico": per un doppione non si può usare l'ID reale del contatto Bitrix, perché collide con il lead originale sulla chiave (cliente, ID Bitrix) e lo sovrascriverebbe. Per questo il workflow genera un ID nuovo e unico a ogni esecuzione nel formato dup-<idContattoTrovato>-<idEsecuzione>. Lo stesso ID viene usato sia dalla registrazione del doppione sia dalla chiamata che lo marca, così le due combaciano sempre.
Nota importante sui test: testa i doppioni solo con un'esecuzione completa dal webhook. Se esegui i nodi uno alla volta, l'ID di esecuzione cambia tra un nodo e l'altro e la marcatura "doppione" non trova il lead corrispondente: resta un segnale "in attesa" che non sparisce.
I lead di altri clienti (es. quelli che arrivano da Bitrix24) seguono lo stesso schema: webhook -> n8n -> ingest con il token del cliente. Cambiano solo la sorgente dei dati e la mappatura dei campi.
In sintesi
Il frontend non decide nulla: mostra ciò che Supabase ha già calcolato. Le uniche cose che tu governi da qui sono le mappature (campi, campagne, spesa, liste) e le regole di ignoro. Tutto il resto — creazione lead, doppioni, pulizia, conteggi — è automatico tra n8n e Supabase.