Introduzione
Il campo Monetary in Odoo è spesso sottovalutato: all'apparenza sembra un numero qualsiasi, sotto il cofano è memorizzato come float, ma il suo comportamento è pensato per gestire il denaro. Capirne la natura ti farà evitare l'errore di usare un semplice Float per valori monetari.
Se hai mai visualizzato il totale di un ordine di vendita, l'importo di una fattura o il prezzo di un prodotto in Odoo, hai già visto un campo Monetario in azione. È presente in moltissimi modelli e si occupa in background della formattazione, dell'arrotondamento e della precisione legata alle valute.
Questa guida è pensata per sviluppatori Odoo, consulenti e utenti tecnici che vogliono comprendere il comportamento reale del campo Monetario. Che tu stia seguendo un tutorial, sviluppando un modulo personalizzato o cercando perché i totali arrotondano in modo diverso dal previsto, qui trovi le informazioni pratiche e i pattern da applicare.
Che cos'è il campo Monetario in Odoo
Il tipo fields.Monetary è uno dei tipi di campo fondamentali del framework Odoo: è stato creato per memorizzare valori espressi in valuta—prezzi, importi, totali di fatture, budget e qualsiasi numero che rappresenti denaro.
La differenza principale rispetto a un Float generico è che il campo Monetario è sempre collegato a una valuta. Conosce quale valuta usare e, sulla base di questa, decide quante cifre decimali mostrare e come arrotondare i valori.
Come si presenta nell'interfaccia
Nell'interfaccia Odoo il campo Monetario mostra il valore formattato secondo la valuta associata: per l'Euro visualizzerà ad esempio € 1.234,50, per il Dollaro statunitense $ 1,234.50. Le cifre decimali e il simbolo seguono la configurazione del record di valuta.
Il campo è modificabile nei form, si mostra ordinato nelle liste e si integra senza problemi in pivot e report finanziari: gli utenti finali non devono occuparsi della formattazione perché Odoo la gestisce automaticamente.
Tipo di dato sottostante
A livello di database il valore è salvato come float a doppia precisione su PostgreSQL. L'informazione sulla valuta non risiede nella stessa colonna: è memorizzata in un record res.currency collegato tramite un campo Many2one nel medesimo modello.
Questa separazione tra valore e valuta è voluta: mantiene i campi del database puliti e permette di cambiare la valuta di un record senza alterare direttamente la colonna numerica.
Come funziona il campo
Conoscere questi meccanismi ti aiuta a usare il campo Monetario correttamente ed evitare problemi di arrotondamento o visualizzazione che spesso emergono nelle personalizzazioni.
Il parametro currency_field
Ogni campo Monetary deve essere associato a un campo Many2one che punti a res.currency. Di default Odoo cerca un campo chiamato currency_id nello stesso modello, ma puoi indicarne uno diverso tramite il parametro currency_field:
amount = fields.Monetary(string='Amount', currency_field='currency_id')Se il campo valuta non esiste o non è impostato, Odoo ricorre alla valuta della company: questo evita errori critici ma in scenari multi-valuta può portare a rappresentazioni sbagliate. È buona pratica dichiarare sempre esplicitamente il campo valuta.
Arrotondamento e precisione
Una differenza chiave rispetto al Float è il comportamento di arrotondamento. Il modello res.currency definisce quante decimali usare e il fattore di arrotondamento per ogni valuta. Quando Odoo legge o mostra un Monetary applica queste regole.
Per esempio, un valore memorizzato come 1.2349999 per una valuta con due decimali verrà mostrato come 1,23. Questo dettaglio è fondamentale per calcoli fiscali, totali di fattura e riconciliazioni: usare un Float in questi contesti può generare discrepanze difficili da tracciare.
Interazione con l'ORM di Odoo
Nell'ORM Odoo la lettura di un campo Monetary restituisce sempre un float Python. Il contesto di valuta proviene dal campo Many2one associato allo stesso record. Quando fai calcoli in Python su valori monetari, usa il metodo round() della valuta per mantenere la precisione:
rounded_value = self.currency_id.round(self.amount)Questo aiuta a evitare errori di accumulo dovuti ai numeri in virgola mobile che possono emergere in totali multilinea o calcoli iterativi.
Campi Monetary nei report QWeb
Nei template QWeb i campi Monetary si integrano con un widget dedicato che formatta correttamente i valori in PDF e report web:
<span t-esc="record.amount"
t-options='{"widget": "monetary", "display_currency": record.currency_id}'/>In questo modo i documenti generati mostrano simboli e decimali corretti in base alla valuta impostata sul record.
Esempi pratici per le aziende
I campi Monetary sono diffusi nei moduli standard Odoo. Di seguito cinque esempi concreti che spiegano dove contano realmente nei processi aziendali.
1. Vendite: prezzi e totali d'ordine
Campi come price_unit, price_subtotal e amount_total nelle vendite sono Monetary. Rispettano automaticamente la valuta selezionata sull'ordine cliente, anche quando differisce dalla valuta della company.
Se un commerciale crea un ordine in USD per una azienda che opera in EUR, Odoo gestisce visualizzazione, arrotondamento e conversioni correttamente perché il campo lavora nel contesto della valuta del record e non della valuta di sistema.
2. Contabilità: importi di fattura e righe IVA
In contabilità tutte le colonne di importo sulle fatture sono campi Monetary: amount_untaxed, amount_tax, amount_total. La valuta impostata sulla fattura guida l'arrotondamento di questi valori.
Questo non è un dettaglio marginale: arrotondamenti errati sulle righe IVA possono generare disallineamenti nei movimenti contabili difficili da riconciliare. Il comportamento currency-aware del campo Monetario previene questi problemi.
3. CRM: revenue atteso nelle opportunità
Il campo expected_revenue nelle opportunità CRM è Monetary. Le squadre di vendita possono registrare valori nel conto del prospect, mentre dashboard e report convertono i numeri in valuta aziendale per l'analisi del pipeline e le previsioni.
Questa logica funziona perché i campi Monetary mantengono il riferimento alla valuta insieme al valore numerico.
4. Acquisti: prezzi fornitore e ordini d'acquisto
Negli acquisti i campi Monetary sono usati per prezzi unitari e totali, legati alla valuta concordata con il fornitore. Una fattura in Yen viene trattata come una fattura in Euro: il campo si occupa di precisione e visualizzazione senza interventi manuali.
5. Campi personalizzati: budget e obiettivi
Richieste comuni di personalizzazione includono campi per budget, target di ricavi o massimali di costo. In tutti i casi il campo giusto è Monetary: si integra con la valuta aziendale, mostra correttamente i valori nelle viste e si comporta prevedibilmente in report ed export.
Usare un Float è possibile, ma in scenari multi-valuta porta subito a incongruenze di formattazione e problemi di arrotondamento.
Creare o personalizzare il campo
Ci sono due strade principali per aggiungere un campo Monetary a un modello Odoo: Odoo Studio per chi preferisce il no-code, o un modulo Python per un controllo completo.
Utilizzare Odoo Studio
Odoo Studio offre il tipo Monetary nella creazione di campi. Quando aggiungi un Monetary con Studio, viene creato automaticamente un campo currency_id se non è già presente sul modello, semplificando la vita senza scrivere codice.
Nota pratica: i campi creati da Studio hanno il prefisso x_ (es. x_studio_budget). Se il modello ha già un currency_id, il nuovo campo lo riutilizzerà; altrimenti Studio crea un nuovo campo valuta. Se prevedi più campi Monetary con valute diverse, verifica la struttura prima della messa in produzione.
Per scenari semplici Studio è la via più rapida e funzionale per utenti non sviluppatori.
Approccio tecnico: campi in Python
In un modulo personalizzato in Python, dichiarare un campo Monetary richiede sempre due definizioni: il campo monetario e il campo Many2one per la valuta. Questo è il pattern standard nello sviluppo Odoo:
from odoo import fields, models
class ProjectTask(models.Model):
_inherit = 'project.task'
x_budget = fields.Monetary(
string='Budget',
currency_field='x_budget_currency_id',
)
x_budget_currency_id = fields.Many2one(
comodel_name='res.currency',
string='Budget Currency',
default=lambda self: self.env.company.currency_id,
)Impostare la valuta della company come valore predefinito è spesso la scelta più pratica per campi interni: evita che la valuta risulti vuota su nuovi record e preserva la formattazione del campo.
Campi Monetary calcolati
I campi Monetary funzionano bene come campi compute. Se devi sommare righe o applicare una formula che restituisce un importo monetario, dichiara il campo come compute e usa il campo valuta associato:
x_total_budget = fields.Monetary(
string='Total Budget',
currency_field='currency_id',
compute='_compute_total_budget',
store=True,
)
@api.depends('x_line_ids.x_amount')
def _compute_total_budget(self):
for record in self:
record.x_total_budget = sum(record.x_line_ids.mapped('x_amount'))L'attributo store=True è fondamentale se vuoi filtrare, ordinare o aggregare su quel campo nelle viste o nei report: i campi compute non memorizzati non possono essere usati nei domini ORM.
Aggiungere un campo Monetary tramite API
Se devi creare campi programmaticamente via XML-RPC (per esempio in uno script di configurazione remota), puoi creare il campo attraverso ir.model.fields:
models.execute_kw(ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_budget',
'field_description': 'Budget',
'model_id': model_id,
'ttype': 'monetary',
'currency_field': 'currency_id',
'state': 'manual',
}]
)Questa è una delle possibilità dell'API XML-RPC per personalizzare Odoo, argomento che trattiamo in altri articoli della nostra raccolta.
Buone pratiche
Il campo Monetary è facile da usare se segui alcuni pattern consolidati. Di seguito le pratiche che tengono il modello pulito e riducono i problemi.
1. Mai usare Float per valori finanziari
Questa è la regola più importante: se un campo rappresenta un prezzo, un importo, un totale o un budget, usa fields.Monetary. Un Float non ha consapevolezza della valuta e non arrotonda correttamente; il campo Monetary è pensato proprio per questo scopo.
2. Dichiarare sempre esplicitamente il campo valuta
Non affidarti alla caduta automatica su currency_id a meno che quel campo non esista realmente. Imposta sempre il parametro currency_field e dichiara il corrispondente Many2one a res.currency. Questo evita fallback silenziosi in ambienti multi-valuta.
3. Impostare una valuta di default
Per campi interni che useranno quasi sempre la valuta aziendale, metti un default: default=lambda self: self.env.company.currency_id. Eviterai che il campo appaia vuoto su nuovi record e perderai il simbolo e la formattazione.
4. Usare store=True su computed che devono essere cercabili
Se definisci un campo compute Monetary e prevedi di filtrare o ordinare per esso, imposta store=True. I campi non memorizzati non possono entrare nei domini ORM o nelle viste basate su SQL.
5. Applicare currency.round() nei calcoli intermedi
Quando esegui più operazioni aritmetiche su valori monetari in Python, applica self.currency_id.round(value) ai passaggi chiave, non solo alla fine. Gli errori di floating-point si accumulano e arrotondare per tempo evita discrepanze sui totali.
6. Essere precisi nei report multi-valuta
Nelle aggregazioni su record con valute diverse non sommare i numeri grezzi: prima normalizza tutto in una valuta comune usando res.currency.compute(), o rendi il report specifico per una valuta. Mischiare valute in una somma genera risultati senza valore finanziario.
Errori comuni
Anche sviluppatori esperti incontrano problemi con i campi Monetary. Ecco gli errori più frequenti e come evitarli.
Errore 1: campo valuta mancante
L'errore più comune quando si aggiunge un Monetary è dimenticare il campo Many2one per la valuta. Se currency_id non esiste, Odoo può ricadere silenziosamente sulla valuta della company in alcuni contesti o sollevare eccezioni in altri. Crea sempre il campo valuta insieme al Monetary.
Errore 2: due Monetary che condividono lo stesso campo valuta ma dovrebbero avere valute diverse
Se sullo stesso modello hai due Monetary destinati a valute diverse (es. prezzo cliente in EUR e costo fornitore in USD), non possono condividere lo stesso currency_id. Ognuno deve avere il proprio riferimento: altrimenti una sola impostazione di valuta sovrascrive entrambi i campi causando dati errati e interfaccia confusa.
Errore 3: discrepanze di arrotondamento nell'aggregazione multi-valuta
Sommare valori Monetari provenienti da valute differenti crea totali che sembrano sbagliati, perché si stanno sommando unità diverse come se fossero omogenee. Questo causa spesso errori nei report aziendali: normalizza le valute prima di aggregare.
Errore 4: confronti su float nelle ricerche ORM
Cercare un Monetary con uguaglianza esatta (es. amount = 10.0) può non restituire i record attesi a causa della rappresentazione floating-point. Usa confronti con margine (>= e <=), o arrotonda con la valuta prima del confronto in logica Python.
Errore 5: ignorare l'arrotondamento della valuta durante l'importazione dati
Importando valori Monetari via CSV o XML-RPC, i numeri vengono salvati così come forniti, senza arrotondamento automatico. Se i dati di origine hanno più decimali di quelli consentiti dalla valuta, i valori memorizzati potrebbero visualizzarsi diversamente e generare piccole discrepanze. Applica l'arrotondamento nel tuo script di importazione prima di inviare i dati a Odoo.
Conclusione
Il campo Monetary è un tipo che sembra semplice ma nasconde comportamenti fondamentali: il suo legame con il record di valuta garantisce arrotondamenti corretti, formattazioni coerenti e gestione currency-aware in tutta l'interfaccia e nel motore di reportistica.
Usarlo correttamente—associare sempre un campo valuta esplicito e non sostituirlo con un Float—ti risparmierà bug sottili e costosi da risolvere in produzione. Il data model di Odoo è pensato attorno a questo tipo di campo per ragioni pratiche.
Che tu stia seguendo una guida per sviluppatori, personalizzando moduli standard o costruendo soluzioni tailor-made, definire bene i tuoi campi Monetary è una decisione fondamentale per la correttezza del trattamento dei soldi nel sistema.
Serve aiuto per la tua implementazione Odoo?
Noi di Dasolo supportiamo aziende nell'implementazione, personalizzazione e ottimizzazione di Odoo su progetti di ogni dimensione. Se ti servono un modello dati pulito, strategie per i campi, supporto multi-valuta o una rollout completa, abbiamo competenze tecniche e funzionali per farlo bene.
Se hai dubbi sui campi Monetary o altri aspetti della tua implementazione Odoo, possiamo aiutarti volentieri. Contattaci e parliamo del progetto che vuoi realizzare.