Introdução
O campo Monetário é um dos tipos de campo mais úteis e mais frequentemente mal utilizados no Odoo. Parece um número, armazena como um float, mas não se comporta como nenhum dos dois. Uma vez que você entender o que o torna diferente, nunca mais usará um Float simples para um valor financeiro.
Se você já olhou para o total de um pedido de venda, um valor de fatura ou um preço de produto no Odoo, você já usou um campo Monetário. Eles estão em toda parte no modelo de dados do Odoo e fazem silenciosamente muito do trabalho pesado em torno da formatação de moeda, arredondamento e precisão.
Este guia é para desenvolvedores do Odoo, consultores e usuários de negócios com mentalidade técnica que desejam entender como o campo Monetário realmente funciona. Quer você esteja seguindo um tutorial de campo do Odoo, construindo um módulo personalizado ou apenas tentando entender por que seus valores estão arredondando de forma diferente do esperado, esta é a referência que você precisa.
O que é o campo Monetário no Odoo
O tipo fields.Monetary é um dos tipos de campo principais no framework Odoo. Ele é projetado especificamente para armazenar valores denominados em moeda: preços, quantias, totais, orçamentos ou qualquer número que represente dinheiro.
O que o torna distinto de um Float regular é a relação obrigatória com uma moeda. Um campo Monetário sempre sabe com qual moeda está trabalhando e usa essa moeda para determinar quantas casas decimais exibir e como arredondar os valores armazenados.
Como Aparece na Interface
Na interface do Odoo, um campo Monetário exibe o valor formatado de acordo com a moeda associada. Se a moeda for Euro, você verá algo como € 1.234,50. Se for o Dólar Americano, você verá $ 1.234,50. O número de casas decimais segue a configuração do registro da moeda.
O campo é totalmente editável em visualizações de formulário, exibe-se de forma limpa em visualizações de lista e integra-se naturalmente em tabelas dinâmicas e relatórios financeiros. Os usuários finais não precisam se preocupar com a formatação. O Odoo lida com isso de forma transparente.
O Tipo de Dados Subjacente
No nível do banco de dados, um campo Monetário é armazenado como um float de precisão dupla no PostgreSQL. As informações da moeda não são armazenadas na mesma coluna. Elas vêm de um registro relacionado res.currency, vinculado através de um campo Many2one separado no mesmo modelo.
Essa separação de valor e moeda é intencional. Ela mantém os campos do banco de dados do Odoo limpos e torna possível mudar a moeda de um registro independentemente dos valores armazenados.
Como o campo funciona
Compreender a mecânica por trás do campo Monetário ajudará você a usá-lo corretamente e evitar o tipo de problemas de arredondamento ou exibição que são surpreendentemente comuns no desenvolvimento personalizado do Odoo.
O Parâmetro currency_field
Todo campo Monetário deve ser emparelhado com um campo Many2one apontando para res.currency. Por padrão, o Odoo procura um campo chamado currency_id no mesmo modelo. Você pode substituir isso com o parâmetro currency_field:
amount = fields.Monetary(string='Amount', currency_field='currency_id')Se o campo de moeda estiver ausente ou não definido em um determinado registro, o Odoo recorre à moeda da empresa. Isso evita erros graves, mas em um ambiente de múltiplas moedas, produzirá formatação incorreta. Sempre declare o campo de moeda explicitamente.
Arredondamento e Precisão
Uma das principais diferenças entre Monetário e Float é como o arredondamento funciona. O modelo res.currency define o número de casas decimais e o fator de arredondamento para cada moeda. Quando o Odoo lê ou exibe um valor Monetário, aplica essas regras automaticamente.
Isso significa que um valor armazenado como 1.2349999 para um campo EUR será exibido como 1.23, não 1.235 ou 1.23499. Isso é crítico para cálculos de impostos, totais de faturas e qualquer processo de reconciliação financeira. Usar um Float simples nesses contextos eventualmente produzirá discrepâncias de arredondamento que são difíceis de rastrear.
Interação com o ORM do Odoo
No ORM do Odoo, ler um campo Monetário sempre retorna um float do Python. O contexto da moeda vem do campo de moeda emparelhado no mesmo registro. Ao fazer cálculos em Python que envolvem campos Monetários, use o método round() da moeda para preservar a precisão:
rounded_value = self.currency_id.round(self.amount)Isso evita erros de acumulação de ponto flutuante que podem aparecer em totais de várias linhas ou cálculos iterativos.
Campos Monetários em Relatórios QWeb
Em modelos de relatório QWeb, campos Monetários integram-se com um widget dedicado que formata o valor corretamente em PDFs e relatórios web:
<span t-esc="record.amount"
t-options='{"widget": "monetary", "display_currency": record.currency_id}'/>Isso garante o símbolo de moeda correto e a formatação decimal em cada documento gerado, independentemente da moeda no registro.
Casos de uso empresarial
Os campos monetários são utilizados em todos os módulos padrão do Odoo. Aqui estão cinco exemplos concretos que ilustram onde e por que eles são importantes em fluxos de trabalho empresariais reais.
1. Vendas: Preços de Produtos e Totais de Pedidos
Campos como price_unit, price_subtotal e amount_total em pedidos de venda e linhas de pedido são todos campos Monetários. Eles respeitam automaticamente a moeda selecionada no pedido do cliente, que pode diferir da moeda operacional da empresa.
Quando um representante de vendas cria um pedido em USD para uma empresa que opera em EUR, o Odoo lida com a exibição, arredondamento e conversão corretamente porque o campo Monetário sempre funciona no contexto da moeda do registro, e não na moeda do sistema.
2. Contabilidade: Valores de Faturas e Linhas de Imposto
No módulo de contabilidade, cada coluna de valor em uma fatura é um campo Monetário: amount_untaxed, amount_tax, amount_total. A moeda definida na fatura determina o arredondamento de todos esses valores.
Isso não é um detalhe. Um arredondamento incorreto nas linhas de imposto cria desequilíbrios nas entradas do diário que são difíceis de reconciliar. O arredondamento consciente da moeda do campo Monetário é o que previne esses problemas no nível dos dados.
3. CRM: Receita Esperada em Oportunidades
O campo expected_revenue em uma oportunidade de CRM é um campo Monetário. As equipes de vendas podem capturar valores de pipeline na moeda do prospecto, enquanto painéis e relatórios convertem tudo para a moeda da empresa para análise de pipeline e previsão.
Essa configuração funciona de forma limpa precisamente porque os campos Monetários carregam informações de moeda juntamente com seu valor numérico.
4. Compras: Preços de Fornecedores e Pedidos de Compra
Os pedidos de compra utilizam campos Monetários para preços unitários e totais, vinculados à moeda acordada com o fornecedor. Uma fatura de fornecedor em Ienes Japoneses é tratada da mesma forma que uma em Euros. O campo Monetário cuida da precisão e exibição sem qualquer manuseio manual da equipe de compras.
5. Campos Personalizados: Orçamento e Acompanhamento de Metas
Um pedido de personalização muito comum é adicionar um valor de orçamento, uma meta de receita ou um teto de custo a um projeto, departamento ou modelo personalizado. Em todos esses casos, um campo Monetário é a escolha certa. Ele se integra naturalmente com a moeda da empresa, exibe corretamente em formulários e listas, e se comporta de maneira previsível em relatórios e exportações.
Usar um Float para esse tipo de campo é tecnicamente possível, mas leva a inconsistências de formatação e problemas de arredondamento assim que surgem cenários de múltiplas moedas.
Criando ou personalizando o campo
Existem duas maneiras principais de adicionar um campo Monetário a um modelo Odoo: através do Odoo Studio para uma abordagem sem código, ou através de um módulo Python personalizado para controle total.
Usando o Odoo Studio
O Odoo Studio inclui um tipo Monetário em seu painel de criação de campos. Quando você usa campos do Odoo Studio para adicionar um campo Monetário a um modelo, o Studio adiciona automaticamente um campo currency_id se um não existir já nesse modelo. Isso cobre os casos de uso mais comuns sem escrever nenhum código.
Uma coisa a ter em mente: os campos criados pelo Studio usam o prefixo x_ (por exemplo, x_studio_budget). Se seu modelo já tiver um campo currency_id, o novo campo Monetário o utilizará. Caso contrário, o Studio criará um novo. Quando você tem vários campos Monetários no mesmo modelo com moedas potencialmente diferentes, esse campo de moeda compartilhado vale a pena revisar cuidadosamente antes de entrar em produção.
Para cenários simples, o Studio é a maneira mais rápida de criar campos no Odoo e funciona bem para usuários de negócios que não têm acesso ao desenvolvimento.
Abordagem Técnica: Campos Python
Em um módulo Odoo personalizado, criar um campo Monetário requer duas declarações: o campo em si e o campo de moeda associado. Este é o padrão padrão no desenvolvimento de campos Python do Odoo:
from odoo import fields, models
class ProjectTask(models.Model):
_inherit = 'project.task'
x_budget = fields.Monetary(
string='Orçamento',
currency_field='x_budget_currency_id',
)
x_budget_currency_id = fields.Many2one(
comodel_name='res.currency',
string='Moeda do Orçamento',
default=lambda self: self.env.company.currency_id,
)Definir a moeda da empresa como padrão é uma escolha prática para a maioria dos campos internos. Isso evita que o campo de moeda apareça vazio quando um usuário abre um registro pela primeira vez, o que quebraria a formatação do campo Monetário.
Campos Monetários Computados
Os campos monetários funcionam bem como campos computados do odoo. Se você precisar totalizar valores de linha ou aplicar uma fórmula que produza um resultado monetário, este é o padrão padrão:
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 é importante se você planeja filtrar, classificar ou agregar neste campo em visualizações de lista ou relatórios. Campos computados não armazenados não podem ser usados em filtros de domínio ORM.
Adicionando um Campo Monetário via API
Se você precisar criar campos no Odoo programaticamente via XML-RPC (por exemplo, como parte de um script de configuração remota), você pode criar o campo Monetário através de 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',
}]
)Isso faz parte do conjunto de ferramentas de personalização do odoo disponível através da API XML-RPC, que é abordada com mais detalhes em outros artigos desta coleção de blogs.
Melhores práticas
O campo Monetário é simples de usar uma vez que você conhece os padrões. Aqui estão as práticas que manterão sua implementação limpa e evitarão problemas no futuro.
1. Nunca Use Float para Valores Financeiros
Esta é a regra mais importante no desenvolvimento do odoo quando se trata de dinheiro. Se um campo representa um preço, um valor, um total, um orçamento ou qualquer número em moeda, use fields.Monetary. Um campo Float não tem consciência da moeda e não arredondará corretamente entre diferentes moedas. O campo Monetário existe precisamente para resolver esse problema.
2. Sempre Declare o Campo de Moeda Explicitamente
Não confie na recuperação do currency_id do Odoo, a menos que esse campo realmente exista no seu modelo. Defina explicitamente o parâmetro currency_field e sempre declare o correspondente Many2one para res.currency. Isso torna a relação clara e evita comportamentos silenciosos de recuperação em ambientes multi-moeda.
3. Defina uma Moeda Padrão
Para campos internos que quase sempre usarão a moeda da empresa, defina um padrão no campo de moeda: default=lambda self: self.env.company.currency_id. Isso evita que o campo apareça em branco em novos registros, o que removeria o símbolo da moeda e a formatação na interface do usuário.
4. Use store=True em Campos Monetários Computados que Você Planeja Pesquisar
Se você definir um campo Monetário computado e esperar que usuários ou relatórios filtrem ou classifiquem por ele, defina store=True. Campos computados não armazenados não podem aparecer em domínios ORM ou visualizações baseadas em SQL. Esta é uma fonte comum de confusão ao construir painéis personalizados no Odoo.
5. Use Currency Round() para Cálculos Intermediários
Ao escrever código Python que realiza múltiplos passos aritméticos em valores Monetários, aplique self.currency_id.round(value) em cada passo significativo, em vez de apenas no final. Erros de ponto flutuante se acumulam em várias operações, e aplicar arredondamento cedo evita discrepâncias nos totais.
6. Seja Intencional em Relatórios Multi-Moeda
Ao agregar valores Monetários entre registros com diferentes moedas, não simplesmente some os números brutos. Converta todos os valores para uma moeda comum primeiro usando res.currency.compute(), ou torne o relatório específico para a moeda. Misturar moedas em uma soma produz números que são tecnicamente corretos no nível do campo, mas financeiramente sem sentido.
Erros comuns
Até desenvolvedores experientes do Odoo enfrentam problemas com campos Monetários. Aqui estão os erros mais comuns e como evitá-los.
Armadilha 1: Campo de Moeda Ausente
O problema mais frequente ao adicionar um campo Monetário é esquecer de criar o campo Many2one de moeda associado. Se currency_id não existir no modelo, o Odoo recorrerá silenciosamente à moeda da empresa em alguns contextos e levantará um erro em outros. Sempre crie o campo de moeda juntamente com o campo Monetário, mesmo que você nunca espere que os usuários o mudem.
Armadilha 2: Dois Campos Monetários Compartilhando Um Campo de Moeda com Diferentes Moedas Pretendidas
Se você tiver dois campos Monetários no mesmo modelo que devem conter valores em diferentes moedas (por exemplo, um preço de cliente em EUR e um custo de fornecedor em USD), eles não podem compartilhar com segurança um único campo currency_id. Cada um precisa de sua própria referência de moeda. Não fazer isso significa que uma configuração de moeda substitui ambos os campos, o que produzirá dados incorretos e um comportamento confuso na interface do usuário.
Armadilha 3: Discrepâncias de Arredondamento ao Agregar Através de Moedas
Somar valores de campos Monetários em registros com diferentes moedas produzirá totais que parecem errados, porque você está adicionando montantes em EUR a montantes em USD como se fossem a mesma unidade. Esta é uma fonte comum de erros de relatório em empresas que operam em múltiplas moedas. Sempre normalize para uma única moeda antes de agregar.
Armadilha 4: Comparações de Ponto Flutuante em Pesquisas ORM
Pesquisar um campo Monetário com uma verificação de igualdade exata (por exemplo, procurando registros onde amount = 10.0) pode perder registros devido à forma como os floats são armazenados no banco de dados. Use >= e <= com uma pequena tolerância, ou aplique arredondamento de moeda antes de comparar valores na lógica Python. Este é um problema geral do ORM do Odoo com campos baseados em float, não específico para Monetário, mas é mais relevante quando dinheiro está envolvido.
Armadilha 5: Ignorando o Arredondamento de Moeda Durante a Importação de Dados
Ao importar registros via CSV ou XML-RPC que incluem valores de campos Monetários, os números importados são armazenados conforme fornecidos, sem arredondamento automático. Se seus dados de origem tiverem mais casas decimais do que a moeda de destino permite, o valor armazenado será tecnicamente correto, mas será exibido de forma diferente do esperado, e pode causar pequenas discrepâncias nos totais. Aplique arredondamento de moeda em seus scripts de importação ou etapas de preparação de dados antes de enviar valores para o Odoo.
Conclusão
O campo Monetário é um daqueles tipos de campo do Odoo que parecem simples à primeira vista, mas carregam um comportamento importante por trás. Sua relação estreita com o registro de moeda é o que o torna confiável para dados financeiros: arredondamento correto, formatação consistente e exibição ciente da moeda em toda a interface do Odoo e no motor de relatórios.
Usá-lo corretamente, o que significa sempre emparelhá-lo com um campo de moeda explícito e nunca substituir um Float por valores financeiros, o salvará de uma categoria inteira de bugs sutis que são notoriamente difíceis de rastrear na produção. O modelo de dados do Odoo é construído em torno deste tipo de campo por um bom motivo.
Seja você um guia de desenvolvedor do Odoo, personalizando um módulo padrão ou construindo algo novo do zero, acertar seus campos Monetários é uma das decisões fundamentais que moldam a confiabilidade da sua implementação do Odoo em lidar com dinheiro.
Precisa de ajuda com a sua implementação do Odoo?
Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo em todas as escalas e configurações. Se você precisa de um modelo de dados limpo, uma estratégia de campo personalizada, suporte a múltiplas moedas ou uma implementação completa do Odoo, nossa equipe tem a profundidade técnica e funcional para acertar.
Se tiver perguntas sobre campos Monetários ou qualquer outro aspecto da sua implementação do Odoo, estamos felizes em ajudar. Entre em contacto connosco e vamos conversar sobre o que está a construir.