Introdução
O campo Many2One é uma peça-chave do modelo de dados do Odoo. Sempre que liga uma encomenda de venda a um cliente, atribui um produto a uma categoria ou associa uma tarefa a um projeto está a estabelecer exactamente esse tipo de relação: muitos registos a apontarem para um único registo. Perceber este comportamento é fundamental para quem configura, personaliza ou desenvolve sobre o Odoo, porque influencia consultas, interfaces e relatórios.
Do ponto de vista empresarial, os campos Many2One são os que tornam o Odoo verdadeiramente integrado. Sem eles, cada módulo seria isolado; com eles, a informação circula entre documentos, os utilizadores navegam naturalmente entre entidades relacionadas e as regras de negócio podem propagar-se sem duplicar dados.
Este artigo explica o que é guardado num Many2One, como o ORM do Odoo e a interface o apresentam, as formas de o criar — seja com Odoo Studio, código Python ou via API — e exemplos práticos em CRM, Vendas, Inventário e Contabilidade.
O que é o campo Many2One no Odoo
No ORM do Odoo, um Many2One cria uma referência de um registo para um único registo noutro modelo. A expressão «Many2One» descreve a relação do ponto de vista do modelo atual: muitos registos aqui podem apontar para um só registo lá. Exemplos típicos incluem várias encomendas ligadas a um cliente ou vários produtos pertencentes a uma mesma categoria.
No nível da base de dados, um Many2One é uma chave estrangeira na tabela do modelo atual. Por exemplo, se a encomenda aponta para o cliente de ID 42, a coluna partner_id na tabela sale_order armazena o inteiro 42. Odoo gere automaticamente as junções e a apresentação do nome do registo associado.
Na interface, o Many2One surge como um campo tipo dropdown com pesquisa rápida (typeahead). O utilizador começa a escrever e o Odoo filtra os registos correspondentes em tempo real; ao escolher um elemento, estabelece-se a ligação. O que é mostrado ao utilizador é o nome do registo relacionado, não o seu ID interno — o que torna a experiência mais intuitiva.
Exemplo prático em código Python (definição de campo):
from odoo import fields, models
class SaleOrder(models.Model):
_inherit = 'sale.order'
x_account_manager_id = fields.Many2one(
comodel_name='res.users',
string='Account Manager',
ondelete='set null',
)
O argumento comodel_name identifica o modelo alvo que será referenciado. O atributo ondelete define a ação quando o registo referenciado é apagado: cascade — apagar também o registo atual; set null — limpar a referência; restrict — impedir a eliminação se houver ligações. O valor por defeito costuma ser set null para evitar perdas acidentais.
No Odoo Studio, o campo aparece como Many2One no seletor de campos. Ao arrastar para o formulário, escolhe-se o modelo de destino e o Studio cria o campo automaticamente — ideal para quem prefere não escrever código mas precisa de estabelecer relações entre modelos.
Como funciona o campo
Ao ler um Many2One através do ORM em Python, obtém-se um recordset do registo ligado. Se o campo estiver vazio, recebe-se um recordset vazio. É possível aceder diretamente aos campos do registo relacionado usando a notação por pontos:
order = self.env['sale.order'].browse(1) customer_name = order.partner_id.name customer_city = order.partner_id.city
Essa navegação encadeada é uma das vantagens do ORM: não precisa de escrever joins SQL explícitos. O framework trata das consultas por trás das cenas e fornece acesso directo aos campos relacionados.
Quando se acede via XML-RPC, um Many2One devolve uma lista com dois elementos: o ID inteiro do registo ligado e o nome de exibição, por exemplo [42, "Acme Corp"]. Se não houver ligação, o valor retornado é False. É um detalhe importante ao processar respostas da API em scripts externos.
Atributos principais do campo
A seguir estão as propriedades mais relevantes que se configuram num Many2One no Odoo:
- comodel_name: o nome técnico do modelo alvo; é o parâmetro obrigatório.
- ondelete: controla o comportamento quando o registo referenciado for eliminado. Valores possíveis: 'cascade', 'set null' e 'restrict'. O padrão habitual é 'set null'.
- domain: filtro que limita quais registos aparecem na seleção. Por exemplo, domain=[('customer_rank', '>', 0)] restringe a escolha apenas a clientes.
- context: valores contextuais passados quando se abre o formulário do registo relacionado ou o dropdown; útil para preencher valores predefinidos ao criar um novo registo ligado.
- required: torna o campo obrigatório — o registo não pode ser guardado sem este valor.
- readonly: impede alterações manuais, útil quando a ligação é definida por lógica automática e não deve ser alterada pelo utilizador.
- delegate: quando True, expõe os campos do modelo relacionado directamente no modelo atual (usado para herança de modelos, não para relações normais).
Aparência nas vistas
Num formulário, o Many2One é apresentado com um campo de pesquisa e um botão para abrir o registo relacionado. Esta navegação rápida poupa tempo ao saltar entre documentos sem menus intermédios.
Numa vista de lista, o campo mostra o nome do registo ligado e permite agrupar por esse critério — por exemplo, agrupar encomendas por cliente ou tarefas por projeto — uma funcionalidade muito usada em relatórios e visões comerciais.
Nas pesquisas, os Many2One funcionam como filtros ou critérios de agrupamento. Filtrar o pipeline de vendas por cliente é precisamente filtrar por um campo Many2One.
O inverso natural: One2Many
Toda a relação Many2One tem um reverso lógico: o One2Many. Se as encomendas apontam para o cliente via Many2One, a ficha do cliente pode expor uma lista com todas as encomendas através de um One2Many. Boas práticas de desenvolvimento recomendam definir ambos os lados para facilitar a navegação; o One2Many não cria coluna adicional na base de dados, ele simplesmente deriva dos valores da chave estrangeira existente.
Casos de uso nas empresas
O Many2One está presente por toda a instalação padrão do Odoo. A seguir têm-se cinco exemplos concretos de fluxos de trabalho empresariais onde este campo é determinante.
CRM: ligar leads aos comerciais
No módulo CRM, cada lead/opportunity tem um campo user_id (Many2One para res.users) que indica o comercial responsável. Essa ligação permite filtrar o pipeline por responsável, calcular taxas de conversão por pessoa e atribuir leads em massa — tudo sem código extra. Para ter múltiplos responsáveis ou um gestor de conta dedicado, basta adicionar outro Many2One para o mesmo modelo.
Vendas: ligar encomendas a clientes e tabelas de preços
Uma encomenda de venda tem, pelo menos, partner_id (cliente) e pricelist_id (tabela de preços). Ao escolher um cliente, o Odoo pode preencher automaticamente a tabela de preços, condições de pagamento e morada de entrega com base no registo do cliente, através de métodos onchange que leem o Many2One e populam campos relacionados — um dos benefícios mais visíveis de um modelo de dados bem desenhado.
Inventário: produtos e categorias
Cada produto tem uma categoria (categ_id em product.template) através de um Many2One. A categoria define contas contabilísticas, métodos de valorização e regras de saída no armazém. A correcta atribuição de categorias é vital para relatórios financeiros fiáveis; o Many2One torna isso simples: um menu suspenso por produto e uma categoria partilhada por centenas de artigos.
Contabilidade: lançamentos e diários
Os lançamentos contabilísticos ligam-se a um diário através de journal_id (Many2One em account.move). O diário define sequência de numeração, tipo de movimento (venda, compra, banco, caixa) e contas por defeito. Seleccionar o diário errado num fornecedor ou num pagamento pode colocar lançamentos na rubrica errada do plano de contas — por isso este campo é crítico para a integridade contabilística.
Gestão de projetos: tarefas e projetos
No módulo de Projetos, cada tarefa tem project_id (Many2One em project.task). Essa ligação determina o fluxo de estados, as permissões da equipa e a forma como as folhas de horas são atribuídas. Para empresas de serviços que faturam por projeto, a cadeia Many2One entre folhas de tempo, tarefas e projeto é essencial para reconhecimento de receita e faturação.
Criar ou personalizar um campo Many2One
Três formas principais de adicionar um Many2One, conforme o contexto técnico.
Via Odoo Studio (sem código)
O Odoo Studio é a ferramenta low-code integrada. Para adicionar um Many2One sem programar:
- Abra o Odoo Studio a partir do menu principal.
- Vá ao formulário onde deseja o campo.
- Arraste um campo Many2One do painel de campos para o formulário.
- Nas propriedades, seleccione o modelo alvo a partir da lista.
- Defina o rótulo e, se necessário, um domain para limitar as opções.
- Guarde e feche o Studio.
O Studio cria o campo com o prefixo x_studio_ e injeta-o na vista. O campo fica logo disponível para pesquisa e selecção — uma forma rápida e acessível de ligar entidades sem tocar numa linha de código.
Via Python num módulo personalizado
Para quem desenvolve módulos, os Many2One são definidos em Python — o método recomendado quando precisa de controlo de versão, testes e deploy em vários ambientes:
from odoo import fields, models
class ProjectTask(models.Model):
_inherit = 'project.task'
x_client_contact_id = fields.Many2one(
comodel_name='res.partner',
string='Client Contact',
domain=[('type', '=', 'contact')],
ondelete='set null',
help='The main contact at the client for this task.',
)
Depois da definição no modelo, inclua o campo nas vistas XML relevantes e actualize o módulo para aplicar as alterações à base de dados. Esta via dá controlo total sobre domain, ondelete, métodos compute e constraints — a abordagem padrão para desenvolvimento em produção.
É também recomendável criar o One2Many recíproco no modelo relacionado para permitir navegação em ambos os sentidos:
class ResPartner(models.Model):
_inherit = 'res.partner'
x_task_ids = fields.One2many(
comodel_name='project.task',
inverse_name='x_client_contact_id',
string='Related Tasks',
)
Via API XML-RPC
Se gerir personalizações programaticamente (scripts de deploy, notebooks remotos), pode criar campos Many2One através da API XML-RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_client_segment_id',
'field_description': 'Client Segment',
'model_id': model_id,
'ttype': 'many2one',
'relation': 'res.partner.category',
'on_delete': 'set null',
'state': 'manual',
}]
)
A chave relation indica o modelo alvo; on_delete define o comportamento de eliminação. Ao criar via API, não se esqueça de adicionar também o One2Many inverso para permitir a navegação desde o modelo relacionado — uma regra prática importante em configurações remotas e automatizadas.
Boas práticas
1. Criar sempre o One2Many recíproco
Quando acrescenta um Many2One, crie também o One2Many no modelo alvo. Isso não cria colunas adicionais na base de dados, mas torna a navegação intuitiva para os utilizadores; sem ele, a relação fica apenas numa direcção e os utilizadores não conseguem ver facilmente tudo o que aponta para um registo.
2. Use domain para filtrar escolhas
Um Many2One para res.partner por defeito mostra todos os parceiros (clientes, fornecedores, contactos internos). Se o campo serve apenas para clientes, aplique um domain como [('customer_rank', '>', 0)] para reduzir ruído e evitar selecções incorrectas que podem causar problemas depois.
3. Pense bem no ondelete
A opção ondelete altera significativamente o comportamento. Cascade pode provocar eliminações em cadeia inesperadas; set null costuma ser a escolha mais segura para evitar perdas de dados; restrict é útil quando não se deve permitir a eliminação enquanto existirem ligações activas.
4. Evite duplicar informação que deveria ser um Many2One
Um erro comum é criar campos char para guardar nomes em vez de referenciar um registo já existente via Many2One. Isso duplica dados, prejudica filtragens e provoca inconsistências quando os nomes mudam. Se a informação existe noutro modelo, use uma relação em vez de repetir texto.
5. Use context para preencher valores por defeito
O atributo context permite enviar valores por omissão quando se cria um registo relacionado a partir do dropdown. Por exemplo, ao criar um contacto a partir de um projecto pode pré-preencher o projecto no formulário do contacto, reduzindo trabalho manual e melhorando a consistência dos dados.
Erros comuns
Esquecer o One2Many recíproco
Criar apenas o Many2One e não o One2Many inverso é a falha mais frequente. O efeito é uma relação unidireccional: a partir do registo «pai» não se vê quem o referencia. Os utilizadores acabam por pedir relatórios ou buscas ad hoc para colmatar essa falta, o que poderia ter sido evitado.
Usar cascade de forma descuidada
Definir ondelete='cascade' sem avaliar o impacto pode levar a perdas massivas de dados — por exemplo, apagar uma categoria com cascade poderia eliminar todos os produtos associados. Na maior parte dos cenários de negócio, set null ou restrict são opções mais seguras.
Não verificar False na navegação em Python
Se um Many2One estiver vazio, o seu acesso em Python devolve um recordset vazio (ou False em chamadas API). Acessos encadeados como order.partner_id.country_id.name podem devolver strings vazias silenciosamente se um elo estiver vazio, levando a relatórios incorretos. Verifique sempre a presença do registo quando o campo não for obrigatório.
Apontar para o modelo errado
O res.partner agrega clientes, fornecedores, contactos e empresas. Um Many2One para res.partner sem domain permite seleccionar qualquer um desses tipos. Se a intenção for só clientes, defina um domain adequado; caso contrário, os utilizadores verão opções irrelevantes na lista.
Excesso de Many2One quando um Selection chega
Se os valores possíveis são fixos e muito limitados, um campo Selection é normalmente mais simples e mais eficiente do que um Many2One. Many2One exige um modelo separado e implica junções na base de dados. Para estados ou categorias estáticas com poucas opções, prefira Selection; use Many2One quando a lista for extensa, gerida pelos utilizadores ou partilhada entre modelos.
Conclusão
O campo Many2One é central para a ligação de dados entre módulos no Odoo. Conhecê-lo bem não é só responsabilidade dos programadores: analistas, consultores funcionais e power users que personalizam com Studio também tiram grande benefício ao dominar quando e como usar este tipo de campo.
Resumo das ideias chave: crie sempre o One2Many inverso para facilitar a navegação, aplique domains para manter as listas relevantes, escolha conscientemente o ondelete e evite usar Many2One quando um Selection seria mais apropriado.
Seja a personalização feita com Odoo Studio, com um módulo Python ou via XML-RPC, definir correctamente os campos relacionais desde o início torna a implementação mais fiável e mais fácil de manter a médio e longo prazo.
Na Dasolo, acompanhamos empresas na implementação, personalização e optimização do Odoo em todas as áreas. Quer precise desenhar um modelo de dados limpo, acrescentar relações aos seus formulários ou desenvolver um módulo completo, ajudamos a transformar a sua necessidade em solução. Contacte-nos e vamos conversar sobre o seu projecto Odoo.