Introdução
O campo Monetário no Odoo parece um número comum, mas esconde regras próprias relacionadas com moeda e arredondamentos. Ao dominá-lo, evita-se usar um Float simples para valores financeiros — uma prática que causa erros sutis e difíceis de resolver.
Sempre que vê preços de produtos, totais de encomendas ou valores de faturas no Odoo, está a ver um campo Monetário em ação. Estes campos estão presentes em grande parte do modelo de dados e tratam automaticamente formatação, casas decimais e regras de arredondamento conforme a moeda associada.
Este texto destina-se a consultores, desenvolvedores e utilizadores técnicos que precisam de saber o que realmente acontece por baixo do campo Monetário. Serve como referência prática para quem está a criar módulos, a seguir um tutorial de campos no Odoo, ou a investigar diferenças inesperadas nos arredondamentos.
O que é o campo Monetário no Odoo
Em termos funcionais, fields.Monetary é o tipo concebido para valores expressos em moeda: preços unitários, montantes de fatura, orçamentos e qualquer número que represente dinheiro dentro do sistema.
A principal diferença para um Float comum é a ligação obrigatória a uma moeda. Um campo Monetário sabe qual a moeda do seu valor e usa esta informação para definir quantas casas decimais mostrar e como arredondar o valor apresentado.
Aparência na interface
No ecrã, o campo Monetário mostra o símbolo e a formatação próprios da moeda associada — por exemplo, «€ 1.234,50» ou «$ 1,234.50» dependendo das configurações do registo de moeda. As casas decimais seguidas são definidas pelo registo da moeda em res.currency.
O campo é editável em formulários, apresenta-se adequadamente em vistas de lista e integra-se sem problemas em pivot tables e relatórios financeiros. Para o utilizador, toda a formatação é transparente — o Odoo faz o trabalho pesado.
Tipo de dados subjacente
No banco de dados, o valor do campo Monetário é armazenado como um float de dupla precisão (double precision) no PostgreSQL. A informação sobre qual é a moeda não fica na mesma coluna: essa referência reside numa Many2one para res.currency no mesmo modelo.
Separar valor e moeda é deliberado: mantém a estrutura de dados limpa e permite alterar a moeda de um registo sem modificar o valor armazenado — útil em vários cenários de negócio.
Como funciona este campo
Compreender estes detalhes evita surpresas com arredondamentos e apresentações, e ajuda a diagnosticar discrepâncias comuns no desenvolvimento personalizado do Odoo.
O parâmetro currency_field
Cada campo Monetary precisa de estar associado a uma Many2one para res.currency. Por defeito, o Odoo procura um campo chamado currency_id no mesmo modelo, mas pode apontar para outro campo com o parâmetro currency_field:
amount = fields.Monetary(string='Amount', currency_field='currency_id')Se a referência à moeda estiver ausente numa entidade, o Odoo recorre à moeda da empresa como fallback. Isso evita erros imediatos, mas em ambientes multi-moeda pode levar a formatações e resultados incorretos — por isso declare sempre o campo de moeda explicitamente.
Arredondamento e precisão
Ao contrário do Float, o comportamento de arredondamento do Monetário segue as regras definidas em res.currency, nomeadamente as casas decimais e o fator de arredondamento. O Odoo aplica essas regras quando lê ou mostra o valor.
Na prática, um valor armazenado como 1.2349999 numa moeda com duas casas decimais será apresentado como 1.23 — isto é essencial em cálculos de imposto, totais de faturas e reconciliações. Usar Float em vez de Monetary nestes casos conduz a discrepâncias difíceis de rastrear.
Interação com o ORM do Odoo
No ORM, a leitura de um campo Monetary devolve sempre um float em Python. A informação da moeda vem do campo Many2one emparelhado no mesmo registo. Ao fazer cálculos com campos Monetários, use o método round() da moeda para manter precisão:
rounded_value = self.currency_id.round(self.amount)Isto ajuda a evitar erros acumulados de ponto flutuante em totalizações de linhas ou em cálculos iterativos.
Campos Monetários em relatórios QWeb
Nos templates QWeb existe um widget específico para formatar campos Monetários corretamente em PDFs e relatórios web:
<span t-esc="record.amount"
t-options='{"widget": "monetary", "display_currency": record.currency_id}'/>Esse padrão garante símbolo da moeda e casas decimais corretas em qualquer documento gerado, independentemente da moeda do registo.
Casos de uso empresarial
Os campos Monetários aparecem por todo o Odoo. Seguem-se cinco exemplos práticos que mostram a sua importância nas operações do dia a dia.
1. Vendas: preços e totais de encomenda
Campos como price_unit, price_subtotal e amount_total nas encomendas de venda são Monetary. Eles respeitam automaticamente a moeda escolhida pelo cliente, mesmo que seja diferente da moeda da empresa.
Por exemplo, um vendedor pode registar uma encomenda em USD para uma empresa que opera em EUR e o Odoo trata da formatação, arredondamento e conversão no contexto da moeda do registo — não da moeda de sistema.
2. Contabilidade: valores de fatura e linhas de imposto
Na contabilidade, todas as colunas de montante numa fatura são campos Monetários: amount_untaxed, amount_tax, amount_total. A moeda definida na fatura controla o arredondamento destes valores.
Isto é crítico: arredondamentos incorretos nas linhas de imposto geram desiquilíbrios nas escriturações que são difíceis de conciliar. O comportamento consciente da moeda do campo Monetário evita esse tipo de problema.
3. CRM: receita esperada em oportunidades
O campo expected_revenue numa oportunidade CRM é Monetário. As equipas de vendas podem registar valores na moeda do potencial cliente enquanto dashboards e relatórios convertem para a moeda da empresa para análise e previsão.
Este fluxo funciona porque os campos Monetários trazem consigo a referência à moeda além do valor numérico.
4. Compras: preços a fornecedores e ordens de compra
As ordens de compra usam Monetary para preços unitários e totais, ligados à moeda negociada com o fornecedor. Uma fatura de fornecedor em ienes é tratada do mesmo modo que uma em euros — a precisão e a apresentação ficam garantidas pelo campo.
5. Campos personalizados: orçamentos e metas
Pedidos comuns de personalização incluem um campo de orçamento, objetivo de receita ou limite de custo. Nestes casos, o campo Monetário é o apropriado: integra-se com a moeda da empresa, apresenta-se corretamente e comporta-se de forma previsível em relatórios e exportações.
Embora seja tecnicamente possível usar Float, isso traz inconsistências de formatação e problemas de arredondamento logo que surgem cenários multi-moeda.
Criar ou personalizar o campo
Existem duas formas principais de adicionar um campo Monetário: usar Odoo Studio para uma abordagem sem código ou criar um módulo em Python para controlo total.
Usar o Odoo Studio
O Odoo Studio inclui um tipo Monetário no assistente de criação de campos. Quando o adiciona, o Studio cria automaticamente um campo currency_id se este não existir no modelo. Para a maioria das necessidades simples, isto é suficiente sem escrever código.
Repare que os campos criados pelo Studio trazem o prefixo x_ (por exemplo, x_studio_budget). Se já existir um currency_id, o novo campo usa-o; caso contrário o Studio adiciona outro. Se tiver vários campos Monetários no mesmo modelo com moedas distintas, reveja esta configuração antes de pôr em produção.
Para cenários diretos, o Studio é a forma mais rápida de criar campos e é útil para utilizadores de negócio sem acesso a desenvolvimento.
Abordagem técnica: campos em Python
Num módulo personalizado em Python deve declarar o campo Monetário e o seu campo de moeda Many2one. Este é o padrão habitual na definição de campos no 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,
)Definir a moeda da empresa como valor por defeito é prático para campos internos: evita que a moeda fique vazia em registos novos e assegura a formatação correta no primeiro acesso.
Campos Monetários calculados (computed)
Campos Monetários funcionam bem como campos calculados. Para totalizar linhas ou aplicar fórmulas que resultem em valores monetários, declare o campo como Monetary e implemente o método de cálculo:
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'))O atributo store=True é fundamental se pretende filtrar, ordenar ou agregar por esse campo em vistas ou relatórios. Campos calculados não armazenados não podem ser usados em domains do ORM nem em consultas SQL.
Adicionar um campo Monetário via API
Se criar campos programaticamente (por exemplo via XML-RPC num script de configuração remota), pode criar um campo Monetário em 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',
}]
)Isto faz parte das ferramentas de personalização disponíveis via API XML-RPC, tema mais alargado em outras publicações desta coleção.
Boas práticas
O uso correto do campo Monetário segue alguns padrões claros. Seguindo-os reduz-se a probabilidade de problemas no futuro.
1. Nunca use Float para valores monetários
Regra de ouro: se o campo representa dinheiro — preço, montante, total, orçamento — use fields.Monetary. Float não tem consciência de moeda nem das regras de arredondamento específicas. O Monetary foi criado exatamente para resolver isso.
2. Declare sempre o campo de moeda explicitamente
Não confie no fallback implícito do Odoo para currency_id a menos que esse campo exista no modelo. Defina currency_field e crie a Many2one para res.currency. Isto evita comportamentos inesperados em ambientes multi-moeda.
3. Defina uma moeda por defeito
Para campos internos que normalmente usam a moeda da empresa, coloque um valor por defeito: default=lambda self: self.env.company.currency_id. Evita que o campo apareça sem moeda em novos registos e mantém a formatação consistente.
4. Use store=True em campos calculados que pretende pesquisar
Se um campo Monetário calculado vai ser usado em filtros ou ordenações, marque store=True. Campos não armazenados não aparecem em domains do ORM nem em visualizações baseadas em SQL, o que costuma confundir quem constrói dashboards personalizados.
5. Arredonde com currency.round() em cálculos intermédios
Ao implementar lógica em Python que envolve várias operações aritméticas sobre valores monetários, aplique self.currency_id.round(value) em passos relevantes em vez de arredondar só no fim. Erros de ponto flutuante acumulam-se e o arredondamento faseado mantém totais consistentes.
6. Seja deliberado em relatórios multi-moeda
Ao agregar valores Monetários com moedas diferentes, não some números crus sem conversão. Primeiro normalize para uma moeda comum usando res.currency.compute() ou faça relatórios por moeda. Somar EUR a USD sem conversão gera totais sem significado financeiro.
Erros frequentes
Mesmo programadores experientes cometem erros com campos Monetários. Eis os mais comuns e como os evitar.
Erro 1: faltar o campo de moeda
O erro mais frequente é esquecer a Many2one para a moeda. Se currency_id não existir, o Odoo por vezes usa a moeda da empresa sem avisar e noutros casos gera uma exceção. Crie sempre o campo de moeda juntamente com o Monetário, mesmo que não se espere que os utilizadores o alterem.
Erro 2: dois campos Monetários a partilharem a mesma moeda quando deveriam ser distintos
Se tiver dois campos Monetários no mesmo modelo destinados a moedas diferentes (por exemplo preço do cliente em EUR e custo do fornecedor em USD), não podem partilhar o mesmo currency_id. Cada campo precisa da sua referência de moeda; caso contrário uma configuração sobrepõe-se à outra e os dados ficam incoerentes.
Erro 3: discrepâncias de arredondamento em agregações multi-moeda
Somar campos Monetários de registos com moedas diferentes produz totais que parecem errados se juntar os valores sem conversão. Este é um problema comum em relatórios para empresas com operações internacionais. Sempre converta antes de agregar.
Erro 4: comparações exactas com floats em pesquisas ORM
Procurar valores Monetários com igualdade precisa (por exemplo, amount = 10.0) pode falhar devido à forma como floats são armazenados. Use intervalos (>= e <= com tolerância) ou aplique o arredondamento da moeda antes de comparar em lógica Python. Trata-se de uma limitação geral do ORM com floats, mas ganha relevância quando lidamos com dinheiro.
Erro 5: ignorar o arredondamento de moeda ao importar dados
Ao importar via CSV ou XML-RPC, os valores Monetários são gravados tal como chegam, sem arredondamento automático. Se os dados de origem contiverem mais casas decimais do que a moeda permite, pode haver diferenças na forma como os valores são apresentados e somados. Aplique o arredondamento no script de importação ou na preparação dos dados antes de os enviar para o Odoo.
Conclusão
O campo Monetário é um daqueles tipos que parecem simples mas embutem regras essenciais: a ligação à moeda garante arredondamento correto, formatação consistente e comportamento fiável em toda a interface e nos relatórios do Odoo.
Usá‑lo correctamente — sempre com o campo de moeda explícito e nunca substituindo-o por um Float para valores financeiros — evitará uma série de bugs subtis e dispendiosos em produção. A arquitetura de dados do Odoo baseia-se nesta convenção por razões sólidas.
Seja a desenvolver um módulo, a adaptar um módulo padrão ou a construir algo novo, acertar nos campos Monetários desde o início é uma decisão básica que influencia a fiabilidade do tratamento de dinheiro no seu sistema Odoo.
Precisa de ajuda com a sua implementação Odoo?
Na Dasolo apoiamos empresas na implementação, personalização e otimização do Odoo, em projetos de várias dimensões. Se precisa de clarificar o seu modelo de dados, definir uma estratégia para campos e moedas, ou de um rollout completo, a nossa equipa técnica e funcional ajuda a pôr as coisas a funcionar corretamente.
Se tiver dúvidas sobre campos Monetários ou qualquer outro aspeto da sua implementação Odoo, estamos ao dispor para ajudar. Contacte‑nos e conversemos sobre o que pretende construir.