Cada negócio é diferente. Sua equipe rastreia informações que nenhum software padrão antecipa, e é exatamente aí que os campos personalizados no Odoo entram.
Em vez de forçar seus fluxos de trabalho a se encaixarem em um modelo de dados rígido, o Odoo permite que você adicione novos campos a quase qualquer registro, seja um cliente, um pedido de venda, um produto ou uma fatura. Você decide quais dados capturar, e o Odoo os armazena junto com tudo o mais.
Este guia cobre tudo o que você precisa saber: o que são campos personalizados, como funcionam internamente, como criá-los com ou sem código, e como usá-los de uma maneira que mantenha sua instância do Odoo limpa e fácil de manter.
O que é um Campo Personalizado no Odoo
Um campo personalizado é um campo de banco de dados que você adiciona a um modelo Odoo existente, além do que vem de fábrica. Ele armazena uma peça específica de informação ligada a um registro, exatamente como um campo nativo faria.
No Odoo, os campos personalizados são identificados pelo prefixo x_. Campos criados através do Odoo Studio usam nomes como x_studio_priority_level, enquanto campos adicionados programaticamente podem usar um prefixo específico para seu projeto, como x_dasolo_cost_center.
A partir da interface do utilizador, um campo personalizado parece e comporta-se exatamente como qualquer campo padrão. Pode aparecer em formulários, vistas de lista, filtros, opções de agrupamento e relatórios. Os utilizadores que não conhecem o lado técnico nunca notarão a diferença.
Tipos de Campo Disponíveis
Odoo suporta uma ampla gama de tipos de campo para campos personalizados, cobrindo a maioria das necessidades de dados:
- Texto (Char): Texto curto, como um código de referência ou um rótulo
- Texto Longo: Texto livre em várias linhas para notas ou descrições
- Inteiro: Números inteiros, úteis para contagens ou pontuações
- Decimal (Float): Números com decimais, para medições ou taxas
- Monetário: Montante ciente da moeda, ligado a um campo de moeda
- Booleano: Uma caixa de seleção verdadeiro/falso
- Data / Data e Hora: Data do calendário ou carimbo de data/hora
- Seleção: Uma lista suspensa fixa de opções
- Many2one: Um link para um único registo em outro modelo
- One2many: Uma lista de registos relacionados de outro modelo
- Many2many: Múltiplos registos ligados de outro modelo
- Binary: Anexo de ficheiro
- HTML: Conteúdo de texto rico
Escolher o tipo de campo certo desde o início evita muitos problemas mais tarde. Um campo de seleção é quase sempre melhor do que um campo de texto livre quando o conjunto de valores possíveis é conhecido de antemão.
Como o Campo Funciona
Odoo é construído sobre uma estrutura chamada Odoo ORM (Mapeamento Objeto-Relacional). Cada formulário, vista de lista e registo que você vê na interface é suportado por um modelo Python que mapeia para uma tabela de banco de dados. Quando você adiciona um campo personalizado, o Odoo o regista no ORM e cria automaticamente a coluna correspondente no PostgreSQL.
É isso que torna o modelo de dados Odoo flexível: você não está corrigindo o código-fonte. Você está estendendo o modelo através de uma camada de metadados armazenada na tabela ir.model.fields. O Odoo lê essa tabela na inicialização e constrói os campos dinamicamente.
Campos Definidos em Código vs. Campos Definidos no Banco de Dados
No desenvolvimento Odoo padrão, os campos são definidos diretamente nas classes de modelo Python usando a estrutura Odoo. Uma definição típica de campo parece assim:
from odoo import models, fields
class SaleOrder(models.Model):
_inherit = 'sale.order'
cost_center = fields.Char(string='Centro de Custo')Campos personalizados criados através da interface ou API seguem um caminho diferente: eles são armazenados com state = 'manual' em ir.model.fields e carregados em tempo de execução. Ambas as abordagens produzem uma coluna real no banco de dados e se comportam de forma idêntica do ponto de vista do usuário.
Campos Relacionais e Reciprocidade
Quando você cria um campo Many2one personalizado apontando para outro modelo, o Odoo espera um campo correspondente One2many do outro lado. Isso não é apenas uma convenção: é assim que o ORM do Odoo navega nas relações entre registros.
Por exemplo, se você adicionar um x_project_id (Many2one para project.project) em um pedido de venda, você também deve adicionar x_sale_order_ids (One2many de volta para sale.order) no modelo de projeto. Sem isso, a navegação do projeto para seus pedidos vinculados não é possível através da interface padrão.
Campos Personalizados Computados
Os campos computados do Odoo são campos cujo valor é calculado automaticamente com base em outros campos, em vez de ser inserido pelo usuário. Em personalizações técnicas, você define um método Python e o vincula ao campo usando o parâmetro compute. Esses campos são somente leitura e são atualizados sempre que suas dependências mudam.
Os campos computados são poderosos, mas requerem código. Atualmente, não podem ser criados através do Odoo Studio sem o modo de desenvolvedor e algum conhecimento de Python.
Casos de Uso Empresarial
Campos personalizados aparecem em quase todos os projetos Odoo em que trabalhamos na Dasolo. Aqui estão cinco cenários comuns de fluxos de trabalho empresariais reais.
1. CRM: Qualificando Leads de Forma Mais Precisa
Os leads padrão do Odoo capturam detalhes de contato e estágio do pipeline, mas muitas equipes de vendas precisam de mais. Um campo Selection para "Indústria do Cliente" ou um Many2one vinculando a um modelo interno "Segmento de Mercado" permite que os representantes de vendas qualifiquem leads mais rapidamente e possibilita que a gestão relate sobre o pipeline por segmento.
2. Vendas: Rastreando Códigos de Projetos Internos
Empresas que cobram clientes por projeto muitas vezes precisam anexar um código de projeto interno ou referência de orçamento a cada cotação ou pedido de venda. Um simples Char field chamado "Código do Projeto" em sale.order torna isso possível sem uma integração completa de gerenciamento de projetos. O campo aparece em documentos impressos e pode ser usado para filtrar e agrupar pedidos em relatórios.
3. Inventário: Atributos Específicos do Produto
Além dos atributos padrão de produto do Odoo, as empresas às vezes precisam rastrear especificações técnicas únicas para seu setor. Um fabricante pode adicionar campos para "Período de Garantia (meses)" (Integer), "Padrão de Certificação" (Selection) ou "País de Origem" (Many2one para res.country). Esses campos se integram naturalmente com o formulário do produto e estão disponíveis em relatórios de inventário.
4. Contabilidade: Orçamento e Alocação de Centro de Custo
As equipas de finanças frequentemente precisam etiquetar faturas ou lançamentos contábeis com um centro de custo ou linha de orçamento. Um campo Many2one em account.move que aponta para um modelo personalizado "Centro de Custo" permite uma alocação de custos detalhada sem modificar a configuração de contabilidade analítica do Odoo. Filtros, tabelas dinâmicas e exportações respeitam todos o campo imediatamente após a criação.
5. RH: Dados de Integração Personalizados
Os departamentos de RH frequentemente coletam dados durante a integração que não se encaixam nos campos padrão de empregado: tipos de contrato específicos de um país, categorias de habilidades internas ou referências de atribuição de frota. Campos personalizados em hr.employee mantêm essa informação dentro do Odoo em vez de em uma planilha separada, tornando-a pesquisável e reportável.
Criando ou Personalizando o Campo
Existem duas maneiras principais de criar campos personalizados no Odoo. A escolha certa depende dos seus recursos técnicos e da complexidade que o campo precisa ter.
Opção 1: Odoo Studio (Sem Código)
Campos do Odoo Studio são o caminho mais rápido para os utilizadores de negócios. Com o Studio ativado, você pode adicionar um novo campo a qualquer visualização em poucos cliques:
- Abra o aplicativo e o tipo de registro onde você deseja o campo (por exemplo, um formulário de pedido de venda)
- Clique no ícone do lápis para entrar no modo de edição do Studio
- Arraste um tipo de campo do painel esquerdo para o formulário
- Defina o rótulo do campo, o nome técnico e quaisquer propriedades adicionais
- Salve e saia do Studio
O Studio cria o campo em ir.model.fields com o prefixo x_studio_ e adiciona-o diretamente à vista. Não é necessária nenhuma implementação ou reinício do servidor. Esta é a abordagem recomendada para campos simples que não requerem lógica personalizada.
Opção 2: Personalização Técnica via API
Para equipas que trabalham em projetos de personalização do Odoo, os campos podem ser criados programaticamente usando a API XML-RPC ou escrevendo um módulo em Python. Este é o caminho certo quando você precisa de campos calculados, filtros de domínio complexos ou campos que devem fazer parte de uma base de código controlada por versão.
Usando a API, criar um campo de seleção personalizado em uma ordem de venda parece assim:
# Encontrar o ID do modelo para sale.order
model = models.execute_kw(
db, uid, api_key,
'ir.model', 'search_read',
[['model', '=', 'sale.order']],
{'fields': ['id', 'name']}
)[0]
# Criar o campo personalizado
field_id = models.execute_kw(
db, uid, api_key,
'ir.model.fields', 'create',
[{
'name': 'x_project_type',
'field_description': 'Tipo de Projeto',
'model_id': model['id'],
'ttype': 'selection',
'selection': [('internal', 'Interno'), ('client', 'Cliente'), ('rd', 'P&D')],
'state': 'manual',
}]
)Esta é parte do fluxo de trabalho padrão do guia do desenvolvedor Odoo para adicionar campos sem modificar arquivos de origem. É especialmente útil para configurações remotas e scripts de implantação automatizados.
Para uma abordagem completa de módulo Python, os campos são definidos em uma classe de modelo e carregados através do mecanismo padrão de módulos do Odoo. Esta é a opção mais sustentável para campos que persistirão através de atualizações e precisam ser rastreados no controle de versão.
Adicionando o Campo a uma Vista
Criar um campo não o torna automaticamente visível na interface. Você também precisa adicioná-lo à vista de formulário ou lista relevante. Com o Studio, isso é feito ao mesmo tempo que a criação do campo. Com a personalização técnica, você modifica diretamente o XML da vista ou cria uma vista herdada que injeta o campo na posição correta.
Melhores Práticas
Campos personalizados são fáceis de criar, mas uma arquitetura de campo mal planejada cria problemas que são difíceis de corrigir mais tarde. Estas são as práticas que mantêm as coisas limpas.
Use Campos de Seleção em vez de Texto Livre Sempre que Possível
Se o conjunto de valores possíveis for conhecido com antecedência, use sempre um campo de Seleção em vez de um campo Char. Texto livre leva a entradas inconsistentes ("Cliente", "cliente", "CLIENTE", "Cl.") que quebram filtros e relatórios. Um dropdown impõe consistência sem custo extra.
Nome os Campos de Forma Clara e Consistente
O nome técnico (x_project_type) deve refletir o conteúdo, não a posição no formulário. Um campo chamado x_field_1 é impossível de manter seis meses depois. Use uma convenção de nomenclatura consistente e documente para que serve cada campo.
Não Exagere nos Modelos Nativos
Adicionar dez campos personalizados ao sale.order é geralmente um sinal de que um modelo personalizado seria mais adequado. Se um grupo de campos pertence junto e representa uma nova entidade no seu negócio (um projeto, um contrato, uma certificação), considere criar um modelo personalizado e vinculá-lo com um campo Many2one.
Teste Sempre em um Banco de Dados de Staging
Antes de adicionar campos a uma instância de produção, teste em uma cópia do banco de dados. A criação de campos é geralmente segura, mas adicionar um campo ao modelo errado, ou com o tipo errado, pode exigir limpeza manual. Um ambiente de staging captura esses problemas cedo.
Documente Seus Campos Personalizados
Mantenha um registro de cada campo personalizado que você adicionar: o modelo, o nome técnico, o propósito e quem o solicitou. As implementações do Odoo acumulam campos ao longo do tempo, e sem documentação torna-se impossível saber quais ainda estão em uso e quais podem ser removidos.
Use a Ferramenta Certa para Lógica Computada
Se o valor de um campo depende de outros campos, use um campo computado em vez de pedir aos usuários que o preencham manualmente. Isso evita inconsistências e reduz erros de entrada de dados. Campos computados fazem parte da funcionalidade central dos campos Python do Odoo e estão bem documentados no tutorial técnico oficial do Odoo.
Erros Comuns
Até equipes experientes enfrentam os mesmos problemas com campos personalizados. Aqui estão os que surgem com mais frequência.
Esquecendo o One2many ao Criar um Many2one
Este é o erro técnico mais comum. Se você adicionar um campo Many2one no modelo A apontando para o modelo B, e não criar o correspondente One2many no modelo B, a navegação de B para A fica quebrada. Os usuários não conseguem ver os registros relacionados do outro lado da relação. Sempre crie ambos os campos juntos.
Excluindo um Campo que Contém Dados
Excluir um campo personalizado remove permanentemente a coluna do banco de dados e todos os dados que ele contém. Não há como desfazer. Se houver alguma chance de que o campo ou seus dados sejam necessários no futuro, arquive ou oculte o campo em vez de excluí-lo.
Criando Campos Diretamente em Produção
Fazer alterações diretamente em um banco de dados de produção ao vivo, sem testar primeiro em um ambiente de staging, é um risco mesmo para adições simples de campos. Se algo der errado com a configuração da visualização, os usuários receberão erros. Sempre valide primeiro em um ambiente de teste.
Conflitos de Nomenclatura com Campos Padrão
Odoo rejeitará um nome de campo que já existe no modelo, mas é fácil acidentalmente criar um campo que sobreponha um campo de um módulo que você instala depois. Usar um prefixo específico da empresa (como x_acme_) para seus campos personalizados reduz consideravelmente esse risco.
Adicionando um Campo à Visualização Sem Pensar na UX
Só porque um campo pode ser adicionado a um formulário não significa que ele deva ser visível por padrão. Formulários desordenados desaceleram os usuários. Se um campo for relevante apenas em contextos específicos, coloque-o em uma aba separada ou torne-o visível condicionalmente usando regras de invisibilidade baseadas em domínio.
Misturando Campos do Studio e Campos Técnicos de Forma Inconsistente
Quando um projeto combina personalização do Studio e personalização baseada em código, você pode acabar com campos que têm propósitos sobrepostos ou nomes conflitantes. Concorde com uma estratégia no início do projeto: use o Studio para todos os campos sem código e código para lógica complexa, ou use código para tudo. Misturar ambos sem um plano claro cria dores de cabeça de manutenção.
Conclusão
Campos personalizados são uma das maneiras mais simples e impactantes de adaptar o Odoo ao seu negócio. Eles não requerem modificações no código-fonte, integram-se naturalmente com o restante da plataforma e fornecem aos usuários a captura de dados exata que precisam, sem soluções alternativas.
A chave é planejar antes de construir. Escolha o tipo de campo certo, nomeie as coisas de forma clara, respeite as convenções de campo relacional e documente o que você cria. Uma arquitetura de campo bem projetada torna sua instância Odoo mais fácil de manter e mais fácil de evoluir à medida que seu negócio cresce.
Seja você um usuário do Odoo Studio para campos rápidos sem código ou escrevendo módulos Python como parte de um projeto mais amplo de personalização do Odoo, os princípios subjacentes são os mesmos: combine o campo com os dados, mantenha o modelo limpo e sempre teste antes de implantar em produção.
Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo para se adequar aos seus fluxos de trabalho reais. Se você precisa de alguns campos personalizados adicionados à sua configuração existente ou de um módulo personalizado completo construído do zero, nossa equipe está aqui para ajudar.
Entre em contato conosco se precisar de orientação sobre sua implementação do Odoo. Ficaremos felizes em revisar sua configuração atual e sugerir o caminho mais limpo a seguir.