Introdução
Sempre que definiu uma quantidade numa encomenda, registou os dias ativos de uma tarefa ou atribuiu uma pontuação de prioridade a um lead, já recorreu a um campo inteiro no Odoo. É um dos tipos de campo mais presentes por ser ideal para medidas que só fazem sentido em números inteiros, embora às vezes seja subvalorizado na modelagem de dados.
Saber exactamente como o campo Integer se comporta é relevante tanto para utilizadores que personalizam formulários, quanto para programadores que desenvolvem módulos e consultores que projetam estruturas de dados para clientes.
Este guia explica o que um campo Integer armazena, como se comporta na interface e no ORM do Odoo, como o pode criar com Studio ou em Python, e apresenta exemplos práticos e cuidados a ter na implementação.
O que é o campo Integer no Odoo
No núcleo do Odoo ORM, o campo Integer destina‑se a guardar números inteiros — sem casas decimais. Em termos de base de dados, mapeia para uma coluna PostgreSQL do tipo INTEGER (um inteiro com sinal de 4 bytes, com uma amplitude na ordem dos milhares de milhões).
Para o utilizador, o Integer surge como um controlo numérico simples nos formulários e como uma coluna numérica nas vistas de lista. É apropriado sempre que a métrica representa unidades inteiras: quantidades contáveis, pontuações, dias, números de sequência ou qualquer medida em que frações não façam sentido.
Exemplo prático de definição em código Python
from odoo import fields, models
class ProjectTask(models.Model):
_inherit = 'project.task'
estimated_hours = fields.Integer(
string='Estimated Hours',
default=0,
)O parâmetro string define o rótulo visível na interface, enquanto o default atribui automaticamente um valor sempre que um registo novo é criado.
No Odoo Studio, o tipo aparece como Integer. Campos criados no Studio recebem automaticamente o prefixo x_studio_; quando definidos por código ou via API, escolhe‑se o nome técnico consoante a convenção do módulo.
Como funciona o campo
Ao declarar um campo Integer num módulo, o Odoo cria automaticamente a coluna correspondente na base de dados durante a instalação ou atualização do módulo — não é necessário escrever migrações SQL manuais.
Na base de dados a coluna é do tipo INTEGER. O ORM assegura coerção de tipos: um campo Integer vazio devolve 0 em vez de None ou False. Esta diferença é importante face a outros tipos — por exemplo, Float ou Char podem devolver False quando estão vazios.
Principais atributos do campo
Abaixo estão as propriedades mais úteis que pode configurar num campo Integer:
- string: o rótulo que os utilizadores veem na interface.
- default: valor atribuído a novos registos; por omissão é
0se não for definido. - required: torna o campo obrigatório. Dado que o default é
0, usarrequiredfaz sentido quando pretende impedir guardar com zero. - readonly: impede edição direta pelos utilizadores na interface.
- index: cria um índice PostgreSQL na coluna, acelerando filtros e pesquisas.
- compute: liga‑o a um método Python que calcula dinamicamente o valor com base noutros campos.
- store: em conjunto com
compute, determina se o valor calculado é guardado na base de dados ou recalculado sempre que solicitado. - copy: define se o valor é copiado ao duplicar um registo.
- groups: limita a visibilidade do campo a grupos de utilizadores específicos.
Como aparece nas vistas
Num formulário, um Integer apresenta‑se como um campo de entrada numérica; para números grandes, o Odoo aplica automaticamente separadores de milhar para melhorar a legibilidade.
Em vistas de lista, os inteiros surgem como números alinhados à direita por convenção. Em vistas de pesquisa, suportam filtros como igual, maior que e menor que.
Também pode associar widgets para alterar a apresentação: o widget priority transforma um inteiro em estrelas clicáveis; o widget progressbar mostra uma barra de progresso quando combinado com um valor máximo.
Interação com o ORM do Odoo
Para um programador, ler e escrever campos Integer é directo: o valor é sempre um int em Python. Como campos vazios devolvem 0, ao testar a ausência de um valor tenha cuidado — zero e “não definido” são indistinguíveis sem lógica adicional.
Integers funcionam bem em campos computados e em domínios usados por vistas, ações do servidor e automatizações em todo o ecossistema Odoo.
Casos de uso para empresas
Exemplos de uso prático
1. CRM: pontuação de leads
As equipas de vendas costumam querer priorizar oportunidades com base numa pontuação. Pode acrescentar um campo Integer chamado Lead Score no modelo de oportunidade; a pontuação pode ser atualizada manualmente ou calculada automaticamente por regras — por exemplo, dimensão da empresa ou nível de interação.
Isto facilita ordenar o pipeline por pontuação e concentrar esforços nas oportunidades mais promissoras.
2. Vendas: quantidades mínimas de encomenda
Nos módulos de Vendas e Inventário, campos Integer servem para definir quantidades mínimas de venda ou regras comerciais. Definir um mínimo de 10 unidades impede que o sistema aceite encomendas com quantidade inferior, evitando retrabalho de negociação com clientes.
3. Inventário: regras de reposição
As regras de reposição dependem de inteiros para os limites mínimo e máximo de stock. Quando o inventário desce abaixo do mínimo, o Odoo dispara uma reposição até ao máximo definido. Valores bem calibrados evitam ruptura de stock e excesso de stock.
4. Gestão de projetos: story points e estimativas
Equipas que usam Odoo Project para metodologias ágeis costumam criar um campo Integer para story points ou horas estimadas. Aparece nas tarefas em kanban ou lista e ajuda a medir capacidade e velocidade por sprint.
5. Contabilidade: prazos de pagamento em dias
Nos termos de pagamento, os dias (Net 30, Net 60, etc.) são definidos com campos Integer. Esses valores alimentam o cálculo da data de vencimento das faturas, tornando‑os críticos para o controlo de tesouraria.
Criar ou personalizar o campo Integer
Duas formas principais de adicionar um campo Integer a um modelo: com Odoo Studio (sem código) ou com definições em Python (personalização técnica).
Usar o Odoo Studio
O Studio é a ferramenta visual para adicionar campos e ajustar vistas sem programação. Para criar um Integer no Studio:
- Abra o formulário onde pretende o campo.
- Ative o Studio através do menu no canto superior direito.
- Na lista de campos à esquerda, arraste o tipo Integer para o formulário.
- Defina o rótulo, indique se é obrigatório e configure o valor por defeito.
- Grave e saia do Studio.
O Studio cria o campo com o prefixo x_studio_ e regista a definição em ir.model.fields, tornando‑o imediatamente disponível em formulários e listas.
Usar Python (personalização técnica)
Para desenvolvedores que criam módulos, define‑se o Integer diretamente numa classe de modelo em Python:
from odoo import fields, models
class CrmLead(models.Model):
_inherit = 'crm.lead'
x_lead_score = fields.Integer(
string='Lead Score',
default=0,
index=True,
help='Score from 0 to 100 used to prioritize opportunities',
)Depois de adicionar o campo ao código, execute odoo-bin -u your_module para aplicar as mudanças: a coluna é criada automaticamente na base de dados.
Criar via API XML-RPC
Também pode criar um campo Integer remotamente com a API XML‑RPC do Odoo, útil para deploys automatizados ou quando não há acesso directo ao servidor:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_lead_score',
'field_description': 'Lead Score',
'model_id': crm_lead_model_id,
'ttype': 'integer',
'state': 'manual',
}]
)O valor ttype para um campo Integer é 'integer'. Defina state como 'manual' para indicar que o campo é personalizado.
Campos Integer computados
Campos Integer computados permitem derivar valores automaticamente — por exemplo, contar tarefas abertas associadas a um projeto:
class Project(models.Model):
_inherit = 'project.project'
open_task_count = fields.Integer(
string='Open Tasks',
compute='_compute_open_task_count',
store=True,
)
def _compute_open_task_count(self):
for project in self:
project.open_task_count = self.env['project.task'].search_count([
('project_id', '=', project.id),
('stage_id.fold', '=', False),
])Definir store=True grava o valor na base de dados, permitindo filtrar e ordenar pela coluna sem recalculá‑la continuamente.
Boas práticas
Dicas práticas para tirar máximo partido dos campos Integer
Use Integer para contagens e quantidades inteiras
Opte por Integer quando o valor tiver obrigatoriamente de ser um número inteiro. Para valores monetários, medições com casa decimal ou quantidades fraccionárias, prefira Float ou Monetary.
Defina um valor por defeito adequado
Como Integer por omissão é 0, pense se esse zero tem significado no seu processo. Se zero indicar “não atribuído”, considere lógica adicional ou um campo Boolean que indique se o valor foi realmente definido.
Adicione índice quando for usar o campo em filtros
Se planeia filtrar, agrupar ou ordenar frequentemente por esse campo, acrescente index=True. Um índice acelera consultas em bases de dados grandes, com um custo pequeno em espaço e tempo de escrita, geralmente compensador quando o campo é usado em pesquisas.
Use store=True em campos computados que serão filtrados
Campos computados que precisam de ser usados em domínios ou agrupamentos devem ter store=True. Sem isso, não é possível utilizá‑los eficazmente em filtros ou em operações de group by.
Documente os intervalos válidos
Se o campo tem um intervalo significativo (por exemplo, pontuação 0–100), coloque essa informação no parâmetro help. O texto aparece como tooltip e evita confusões sobre valores aceitáveis.
Pense duas vezes antes de usar Integer para IDs ou referências
Para referenciar outro registo utilize Many2one em vez de guardar um ID numérico num campo Integer. Many2one oferece navegação, regras de cascata e integração com o ORM; um Integer com um ID é frágil e contorna as funcionalidades do Odoo.
Erros comuns
Erros recorrentes ao trabalhar com Integer
Confundir Integer com Float
Um erro comum é escolher Integer quando será necessário armazenar decimais. Se os utilizadores precisarem de 1.5, 0.25 ou percentagens com casas decimais, Integer irá truncar e causar perda de dados. Use Float para precisões decimais e Monetary para valores em moeda.
Assumir que zero significa vazio
Como Integer retorna sempre 0 quando não preenchido, não existe distinção entre “não preenchido” e “zero intencional”. Se essa diferença for relevante, adicione um Boolean (ex.: has_score) ou utilize um Float com default False.
Não criar índice em campos muito filtrados
Adicionar um Integer e depois começar a usá‑lo frequentemente em filtros sem ter colocado index=True pode tornar as vistas lentas em bases de dados grandes. É mais simples planear o índice desde o início do que otimizar depois.
Usar Integer para razões que exigem decimais
Armazenar percentagens como inteiros (ex.: 75 para 75%) funciona até surgir a necessidade de 72.5%. Se houver hipótese de precisar de casas decimais, escolha Float desde o início.
Esquecer store=True em campos computados usados em filtros
Um campo Integer computado sem store=True não pode ser usado em domínios, automatizações ou agrupamentos. Este é um erro frequente — pense sempre onde o campo será usado antes de decidir se o armazena.
Conclusão
O campo Integer é uma peça básica do modelo de dados do Odoo. Apesar da sua aparente simplicidade, comportamentos como o retorno de 0 em campos vazios e a necessidade de store=True para filtros tornam‑no um elemento que convém dominar para evitar problemas difíceis de corrigir mais tarde.
Seja a configurar Odoo para vendas, a programar módulos personalizados ou a definir regras de reposição de stock, os campos Integer surgem em muitos pontos. Conhecer as diferenças face a Float ou Monetary e saber criar e armazenar estes campos contribui para implementações mais sólidas e fáceis de manter.
Quando está a modelar Odoo, investir tempo em compreender estes fundamentos compensa durante todo o ciclo de vida do projecto — menos retrabalho e menos bugs numa fase posterior.
Trabalhe com um especialista Odoo
Na Dasolo, ajudamos empresas a implementar, customizar e otimizar o Odoo em vários módulos e sectores. Desde definir modelos de dados claros a criar campos e fluxos de trabalho personalizados ou integrar Odoo com sistemas externos via API, trazemos experiência prática para fazer o trabalho bem feito.
Se tiver dúvidas sobre a sua configuração Odoo ou quiser conversar sobre um projecto, entre em contacto com a nossa equipa— teremos todo o gosto em ajudar.