Introduzione
In Odoo i modelli stabiliscono la forma dei dati: definiscono tabelle, colonne e relazioni nel database. Ogni entità di business — dalla fattura all'ordine, fino al lead commerciale — è gestita tramite un modello che ne regola struttura e comportamento.
Per consulenti funzionali e sviluppatori, padroneggiare i modelli è fondamentale. Essi costituiscono lo scheletro dell'architettura dati di Odoo: campi, vincoli, relazioni e logiche di business nascono e si applicano qui.
Questo testo si concentra sul modello crm.lead, il cuore del modulo CRM. Che tu stia creando moduli personalizzati, collegando applicazioni esterne o modellando il flusso commerciale, prima o poi interverrai su questo modello.
Cos'è il modello crm.lead
Il modello crm.lead rappresenta lead e opportunità: è il contenitore unico dei dati della pipeline commerciale. Gestisce sia i contatti iniziali non qualificati sia le opportunità qualificate, tenendo traccia della loro evoluzione.
Il CRM è il consumatore principale di crm.lead, ma anche altri moduli (marketing, sito web, vendite) lo arricchiscono o lo consultano. Un form compilato sul sito, un'opportunità creata dal commerciale o la conversione in cliente passano sempre da questo modello.
Nel codice Odoo l'estendibilità passa per l'ereditarietà dei modelli. Il modulo CRM definisce la struttura di base; altri moduli aggiungono campi o comportamenti specifici senza toccare il nucleo, permettendo aggiornamenti più semplici.
Campi principali del modello
Qui trovi i campi più rilevanti di crm.lead: conoscerli aiuta a configurare workflow, report e integrazioni in modo efficace.
1. name
Tipo: Char. Contiene il titolo del lead/opportunità, l'etichetta visibile nelle viste elenco o kanban. Tipicamente descrive l'origine o la natura del contatto, ad esempio “Richiesta da sito web” o il nome dell'affare.
2. contact_name
Tipo: Char. Nome della persona di riferimento quando non c'è ancora un partner collegato. Al momento della conversione questo valore viene spesso trasferito al record res.partner creato o associato.
3. email_from
Tipo: Char. Indirizzo email principale del lead. Usato per comunicare prima della conversione e per riconoscere o unire lead duplicati basandosi sull'email.
4. phone
Tipo: Char. Numero telefonico principale, visibile nella scheda lead e utile per registrare chiamate e attività di follow-up.
5. mobile
Tipo: Char. Cellulare di contatto, spesso usato per comunicazioni immediate o SMS quando diverso dal telefono fisso.
6. partner_id
Tipo: Many2one (res.partner). Collega il lead a un contatto o a un'azienda una volta qualificato o convertito. Prima della conversione rimane vuoto; dopo punta al partner creato o trovato.
7. user_id
Tipo: Many2one (res.users). Il commerciale responsabile del lead. Serve per assegnazioni, reportistica e pianificazione attività e alimenta dashboard come “Le mie opportunità”.
8. team_id
Tipo: Many2one (crm.team). Il team di vendita di appartenenza. Permette assegnazioni a rotazione e report per team.
9. stage_id
Tipo: Many2one (crm.stage). Indica in quale fase della pipeline si trova il lead: Nuovo, Qualificato, Offerta, Negoziazione, Vinto, Perso. Il passaggio tra fasi attiva automazioni e influisce sui report.
10. type
Tipo: Selection. Distingue Lead da Opportunity. I lead sono contatti iniziali, le opportunity sono trattative qualificate con valore stimato; il tipo influisce su viste e fasi disponibili.
11. expected_revenue
Tipo: Float. Valore atteso se l'opportunità viene vinta. Serve per il valore della pipeline e le previsioni; spesso è calcolato con probabilità e importo dell'affare.
12. probability
Tipo: Float. Probabilità di chiusura (0–100%). Usata nei calcoli di pipeline ponderata; può essere impostata manualmente o derivata dalla fase.
13. company_id
Tipo: Many2one (res.company). In scenari multi-company identifica a quale società appartiene il lead, influenzando visibilità e valuta.
14. description
Tipo: Text. Note dettagliate sul lead: riassunti di incontri, messaggi internI e contesto necessario al follow-up.
15. create_date
Tipo: Datetime. Data/ora di creazione del record, gestita automaticamente. Utile per analisi dell'età del lead e dei tempi di conversione.
16. write_date
Tipo: Datetime. Data/ora dell'ultima modifica, sempre aggiornata automaticamente; serve a tracciare l'ultimo aggiornamento.
17. date_open
Tipo: Datetime. Momento in cui il lead è stato assegnato a un utente (quando user_id viene impostato). Utile per misurare il tempo di primo contatto.
18. date_closed
Tipo: Datetime. Data di chiusura del lead (vinto o perso), impostata quando lo stage passa a una fase di chiusura; fondamentale per analisi del ciclo di vendita.
19. date_deadline
Tipo: Date. Data prevista di chiusura dell'affare, utilizzata per pianificare attività e forecast.
20. active
Tipo: Boolean. Flag di archivio: se False il record è nascosto dalle viste predefinite. Lead persi o uniti vengono spesso archiviati anziché cancellati.
21. street, street2, city, zip
Tipo: Char. Campi di indirizzo copiati al partner una volta convertito, utili quando il lead fornisce dati di localizzazione.
22. country_id
Tipo: Many2one (res.country). Nazione del contatto: utile per report territoriali e per formattare correttamente l'indirizzo.
23. state_id
Tipo: Many2one (res.country.state). Regione o provincia; il dominio è vincolato dalla nazione per facilitare la selezione corretta.
24. source_id
Tipo: Many2one (utm.source). Origine del lead: sito, referral, campagna ecc. Fondamentale per l'attribuzione marketing.
25. campaign_id
Tipo: Many2one (utm.campaign). Campagna di marketing associata: permette di collegare il lead a specifiche iniziative per misurare il ROI.
26. activity_ids
Tipo: One2many (mail.activity). Elenco attività programmate (chiamate, riunioni, task) collegate al lead; guida il widget delle attività e i promemoria.
27. color
Tipo: Integer. Indice colore usato in kanban e liste per evidenziare priorità o categorie visive personalizzate.
28. message_ids
Tipo: One2many (mail.message). La chatter: note interne, email e storico attività che raccolgono tutte le comunicazioni sul lead.
Come questo modello entra nei processi aziendali
1. Cattura lead dal sito
Quando un visitatore compila un form sul sito Odoo viene creato automaticamente un crm.lead: il nome, l'email e il testo del messaggio arrivano dal form e il commerciale vede il nuovo record nella pipeline per il primo contatto.
2. Qualificazione e conversione
I commerciali spostano i lead tra le fasi; al momento della qualifica si passa da Lead a Opportunity e si imposta il valore atteso. Alla chiusura positiva il sistema crea o collega un res.partner e, se previsto, genera un ordine di vendita.
3. Report sulla pipeline
I manager si basano sui dati di crm.lead per monitorare la pipeline: valore atteso, probabilità e fase servono per calcolare la pipeline ponderata, mentre i filtri per utente e team mostrano performance individuali e per squadra.
4. Attribuzione marketing
I campi source_id e campaign_id collegano i lead alle attività di marketing: UTM e parametri delle campagne popolano questi campi e permettono di misurare l'efficacia di email, annunci e iniziative.
5. Gestione attività e follow-up
I commerciali pianificano attività sul lead: activity_ids conserva chiamate, incontri e task e la data di scadenza delle attività alimenta la colonna “Prossima attività” per ricordare i follow-up.
Come gli sviluppatori estendono questo modello
Gli sviluppatori estendono crm.lead con diversi approcci: l'ereditarietà del modello è lo strumento principale per aggiungere campi e logiche senza modificare il core.
Ereditarietà del modello
Dichiarare _inherit = 'crm.lead' permette di estendere il modello. Così si aggiungono campi, si sovrascrivono metodi o si applicano vincoli mantenendo le modifiche separate in un modulo dedicato, più semplice da aggiornare.
Aggiunta di campi
Definisci nuovi campi nel modello ereditato usando i tipi corretti (Char, Many2one, Boolean, Integer, Text, Selection). Esempi comuni: fonte personalizzata, interesse prodotto o settore. In ambienti multi-company valuta campi dipendenti dalla società.
Estensioni Python
Sovrascrivi create, write o action_convert per inserire logiche custom, richiamando sempre super() per non interrompere il comportamento di base. Usa i decorator @api.depends e @api.onchange per campi computati e per reagire a modifiche nella UI.
Odoo Studio
Odoo Studio consente di aggiungere campi senza programmare: ottimo per modifiche rapide. Per logiche complesse, automazioni avanzate o esigenze di manutenzione a lungo termine è preferibile sviluppare moduli personalizzati.
Buone pratiche
- Configura le fasi in modo che rispecchino il tuo processo commerciale; se necessario separa la sequenza per lead e opportunity.
- Mappa i parametri UTM dei form del sito verso source_id e campaign_id per assicurare una corretta attribuzione marketing.
- Usa team_id per regole di assegnazione automatiche (round-robin o per territorio). Definisci le regole di assegnazione nel crm.team.
- Per integrazioni API utilizza XML-RPC o JSON-RPC: il modello crm.lead è esposto e conviene mappare gli ID esterni in un campo personalizzato (ad esempio ref) per sincronizzazioni affidabili.
- Per i campi personalizzati usa il prefisso x_ o il prefisso del modulo per evitare conflitti con futuri rilasci di Odoo.
Errori comuni
- Creare lead duplicati senza cercare per email_from. Prima di creare un lead verifica duplicati normalizzando l'email o eseguendo controlli di deduplicazione.
- Confondere type (Lead vs Opportunity) con stage_id. Il type identifica la natura del record; lo stage la posizione nel funnel: entrambi impattano report e automazioni.
- Dimenticare di impostare user_id o team_id. Lead non assegnati rischiano di perdersi: configura assegnazione automatica o assicurati di gestirli manualmente.
- Sovrascrivere la conversione senza chiamare super(). action_convert gestisce operazioni critiche: estendila richiamando la logica esistente anziché rimpiazzarla.
- Aggiungere campi obbligatori senza valori di default. I record esistenti falliranno le validazioni al momento dell'upgrade se non prevedi valori predefiniti.
Conclusione
Il modello crm.lead è il perno del CRM in Odoo: contiene lead e opportunità e guida tutta la pipeline commerciale. Conoscere i suoi campi e le modalità di estensione facilita configurazioni, personalizzazioni e integrazioni.
Che tu stia mappando processi commerciali come consulente funzionale o sviluppando moduli CRM, una buona padronanza di crm.lead riduce tempi e rischi durante l'implementazione.
Hai bisogno di supporto per la tua implementazione Odoo?
Dasolo supporta le aziende nell'implementazione, personalizzazione e ottimizzazione di Odoo. Siamo specializzati in integrazioni API e sviluppo su misura, con esperienza profonda nell'architettura dati e nei modelli come crm.lead.
Se cerchi supporto per implementazioni Odoo, moduli CRM personalizzati o integrazioni, possiamo aiutarti. Prenota una demo per parlare del tuo progetto.