Este texto explica por que o res.partner é tão importante no Odoo, quais os campos que deve conhecer, e como o modelar e estender de forma segura. Destina-se a consultores funcionais, programadores e equipas que vão integrar ou customizar processos com base em contactos.
No Odoo, os modelos são o esquema que organiza e persiste a informação na base de dados. Tudo o que lida com a operação da empresa — clientes, fornecedores, faturas, contactos — existe como registos num modelo.
Conhecer bem os modelos é obrigatório tanto para quem configura processos como para quem os programa. Eles constituem a espinha dorsal dos dados: campos, relações e as regras de negócio estão todos definidos aí.
Este texto concentra-se num modelo crítico do Odoo: res.partner. Se estiver a criar módulos à medida, a ligar sistemas externos ou a desenhar fluxos de trabalho, é muito provável que trabalhe com este modelo.
O res.partner é o modelo que representa todas as “partes” com que o negócio interage: clientes, fornecedores, contactos e entidades legais. Funciona como o registo mestre onde se centraliza a informação de contacto e contexto comercial.
O res.partner é o repositório de informação sobre qualquer entidade com a qual a sua empresa interage: pessoas, empresas, clientes e fornecedores. É ali que ficam guardados os dados básicos de cada parte interessada.
Praticamente todos os módulos do Odoo usam este modelo. Vendas, CRM, Contabilidade, Compras e lojas online recorrem ao res.partner: criar um cliente, um lead ou um fornecedor significa, muitas vezes, criar ou associar um registo em res.partner.
A definição base do modelo está no módulo base, e os restantes módulos expandem-no por herança. O CRM acrescenta campos para leads, a contabilidade adiciona limites de crédito e condições de pagamento — cada módulo complementa o modelo sem duplicar a sua estrutura principal.
Campos-chave a conhecer: name (nome), email, phone/mobile, street/street2/city/zip/state_id/country_id (morada completa), is_company/parent_id/child_ids (hierarquia), company_id (multi-empresa), vat (NIF/IVA), customer_rank/supplier_rank (status comercial), user_id (responsável), type (tipos de morada), ref (referência interna), website, comment, active, lang, image_1920 e category_id (etiquetas). Conhecer estes campos ajuda a mapear requisitos e a integrar com sistemas externos.
A seguir estão os campos mais relevantes do res.partner. Dominar estes atributos facilita muito a gestão de contactos e a integração com outros processos.
1. name
Tipo: Char. Guarda o nome do parceiro — nome da empresa ou nome completo da pessoa. Aparece em muitas vistas como identificação principal do registo.
2. create_date
Tipo: Datetime. Regista quando o registo foi criado. É preenchido automaticamente e serve para auditorias e relatórios temporais.
3. write_date
Tipo: Datetime. Indica a última data/ hora em que o registo foi alterado. Também gerido automaticamente para rastrear atualizações.
4. email
Tipo: Char. Endereço de e‑mail principal, usado para comunicações, acesso ao portal e emissão de documentos. O Odoo valida o formato quando possível.
5. phone
Tipo: Char. Número de telefone fixo principal, visível nas fichas de contacto e em workflows de comunicação.
6. mobile
Tipo: Char. Telemóvel do contacto; útil para notificações urgentes ou SMS quando difere do número principal.
7. street
Tipo: Char. Primeira linha do endereço; faz parte do bloco de morada usado em documentos e formulários.
8. street2
Tipo: Char. Segunda linha do endereço, para referências como apartamento, prédio ou instruções adicionais.
9. city
Tipo: Char. Cidade ou localidade — a formatação do endereço pode variar consoante o país.
10. zip
Tipo: Char. Código postal; relevante para validação da morada e cálculos de expedição.
11. state_id
Tipo: Many2one (res.country.state). Distrito, província ou estado; normalmente filtrado pelo país selecionado e nem todos os países têm este conceito.
12. country_id
Tipo: Many2one (res.country). País do parceiro; influencia a formatação de moradas, regras fiscais e localizações.
13. is_company
Tipo: Boolean. Indica se o registo é uma empresa ou uma pessoa. Empresas podem ter contactos filhos; pessoas ligam‑se a empresas através de parent_id.
14. parent_id
Tipo: Many2one (res.partner). Liga um contacto à sua empresa principal, permitindo heranças de morada e hierarquias empresa–contacto.
15. child_ids
Tipo: One2many (res.partner). A lista inversa de parent_id — mostra todos os contactos associados a uma empresa.
16. company_id
Tipo: Many2one (res.company). Em ambientes multi‑empresa, diz a que empresa do Odoo pertence o parceiro, afectando visibilidade e regras de acesso.
17. vat
Tipo: Char. Número de identificação fiscal/VAT; validado por formato nacional. Importante para emissão de faturas e conformidade fiscal.
18. customer_rank
Tipo: Integer. Indicador de cliente — incrementado quando existem vendas para esse parceiro. Utilizado para filtragem e prioridade em listas e relatórios.
19. supplier_rank
Tipo: Integer. Indicador de fornecedor — incrementado quando existem compras ou faturas de fornecedor. Ajuda a identificar fornecedores activos.
20. user_id
Tipo: Many2one (res.users). Utilizador responsável ou comercial associado ao parceiro; usado para atribuições em CRM e vendas.
21. type
Tipo: Selection. Tipo de morada para contactos filhos: Contact, Invoice, Delivery ou Other. Determina qual a morada usada em documentos.
22. ref
Tipo: Char. Referência interna ou código do parceiro, útil para mapear com sistemas externos ou para numeração personalizada.
23. website
Tipo: Char. URL do website do parceiro; aparece nas fichas e em contextos de comércio electrónico.
24. comment
Tipo: Html. Notas internas visíveis aos utilizadores; frequentemente usadas para instruções comerciais ou detalhes específicos.
25. active
Tipo: Boolean. Bandeira para arquivar registos — quando falso, o parceiro fica oculto nas vistas por omissão sem ser eliminado definitivamente.
26. lang
Tipo: Selection. Idioma preferido do parceiro; permite enviar comunicados e documentos na língua correcta, herdando do parent quando aplicável.
27. image_1920
Tipo: Binary. Imagem ou logótipo do parceiro; o Odoo guarda várias resoluções para uso em formulários, relatórios e site.
28. category_id
Tipo: Many2many (res.partner.category). Etiquetas ou categorias para segmentação e marketing; flexível para classificar parceiros segundo critérios próprios.
No dia a dia das empresas, o res.partner alimenta quase todos os workflows: vendas usam-no para cotações e oportunidades; faturação para endereços e IVA; compras para fornecedores; e lojas online para registos de clientes. Em ambientes multi-empresa, registos podem existir por company_id ou ser consolidados com regras intercompany — é necessário planear para evitar inconsistências.
1. Vendas e CRM
Quando um comercial cria uma proposta, selecciona o cliente a partir de res.partner — o mesmo registo pode ser usado como lead, oportunidade e ordem. Campos como customer_rank e user_id orientam relatórios e atribuições.
2. Facturação
Faturas e notas de cobrança apontam para um partner para a morada de cobrança; o VAT influencia os cálculos fiscais, enquanto limites de crédito e condições de pagamento costumam ser mantidos no parceiro.
3. Compras e Fornecedores
Ordens de compra e faturas de fornecedor ligam‑se ao res.partner. O supplier_rank identifica fornecedores activos, e campos como buyer_id atribuem um responsável pela gestão do fornecedor.
4. Comércio electrónico e Portal
Utilizadores do site podem gerar registos de parceiro ao registar‑se; esses registos alimentam encomendas, cotações e acessos ao portal, com moradas e contactos derivados do parceiro.
5. Multi‑Empresa e Consolidação
Em ambientes com várias empresas, a mesma entidade legal pode aparecer como parceiros distintos por empresa. company_id e regras inter‑empresa definem como e que dados são partilhados.
Os programadores estendem o res.partner sobretudo por herança de modelos. Crie um módulo com _inherit = 'res.partner' para acrescentar campos, restrições ou lógica. Use super() quando sobrescrever create/write/unlink, e limite a lógica pesada em computed fields para não afetar desempenho. Para alterações simples, o Odoo Studio é prático; para requisitos complexos ou duradouros, prefira módulos personalizados.
Os desenvolvedores ampliam o res.partner através de padrões bem definidos, sendo a herança de modelos o mecanismo principal.
Herança de Modelo
Utilize _inherit = 'res.partner' para estender o modelo: adicionar campos, sobrescrever métodos ou impor restrições. A herança mantém as alterações separadas num módulo, facilitando upgrades.
Adicionar Campos
Declare novos campos no modelo herdado usando o tipo adequado: Char, Many2one, Boolean, Integer, Text, Selection. Pense em campos dependentes da empresa em cenários multi‑company.
Extensões em Python
Sobrescreva métodos como create, write ou unlink para lógica personalizada, e chame super() para preservar o comportamento original. Tenha atenção às dependências de campos computados.
Odoo Studio
O Odoo Studio permite adicionar campos sem código — útil para ajustes rápidos. Para lógica complexa ou evoluções de versão, é preferível desenvolver módulos personalizados.
Boas práticas essenciais: manter a hierarquia empresa/contato bem definida (criar a empresa primeiro); usar country_id para formatação e regras fiscais; empregar commercial_partner_id para consolidação; prefixar campos personalizados com x_ ou com o código do módulo; e testar extensões em ambientes de homologação antes de aplicar em produção.
- Crie primeiro a ficha da empresa e depois adicione os contactos com parent_id para manter a hierarquia correcta entre empresa e contactos.
- Defina country_id para garantir que a morada é formatada correctamente e que as regras fiscais aplicáveis são acionadas.
- Use commercial_partner_id quando precisar do nível superior da entidade para agregação — por exemplo, para controlo de crédito ou relatórios consolidados.
- Para integrações API, utilize XML‑RPC ou JSON‑RPC: o modelo res.partner está completamente exposto. Faça o mapeamento de IDs externos com cuidado para evitar inconsistências.
- Para campos personalizados, prefira prefixos como
x_ou um prefixo do seu módulo para minimizar conflitos com futuras versões do Odoo.
Erros frequentes incluem: criar parceiros duplicados em vez de procurar antes de criar; confundir parent_id com company_id; esquecer de definir o tipo (invoice/delivery) em contactos secundários; sobrepor métodos core sem chamar super(); e adicionar campos obrigatórios sem fornecer valores para registos existentes. Estes deslizes complicam upgrades e fluxos de negócio.
- Evite criar parceiros duplicados em vez de procurar os existentes; utilize campos como
email_normalizedourefpara deduplicação automatizada. - Não confunda parent_id com company_id: parent_id liga contacto à empresa pai; company_id define a que empresa do sistema o parceiro pertence.
- Certifique‑se de definir correctamente o campo type em contactos filhos: moradas de facturação e entrega dependem desse tipo para serem usadas nos documentos.
- Nunca sobrescreva métodos core sem chamar
super(); tal prática pode quebrar outros módulos ou dificultar atualizações futuras. - Ao adicionar campos obrigatórios sem valores por omissão, terá erros em registos existentes durante upgrades — forneça defaults ou migre dados corretamente.
Em suma: o res.partner é o nó central de contactos no Odoo. Dominar os seus campos, relações e padrões de extensão evita duplicidade de dados, facilita integrações e melhora processos de vendas, compras e faturação. Invista algum tempo em modelagem e testes antes de lançar alterações em produção.
O res.partner é um dos pilares do Odoo: alberga clientes, fornecedores e contactos. Compreender os seus campos e a forma como outros módulos o estendem é crucial para configurar, personalizar e integrar a plataforma com confiança.
Seja a sua função a modelação de processos ou o desenvolvimento de módulos, dominar o res.partner poupa tempo e reduz riscos operacionais.
Precisa de Apoio na Implementação do Odoo?
A Dasolo presta serviços de implementação, personalização e optimização do Odoo, com foco em integrações API e desenvolvimento à medida. A nossa equipa conhece a arquitectura de dados do Odoo e modelos-chave como o res.partner.
Se precisa de ajuda com implementação, módulos personalizados ou integrações Odoo, estamos disponíveis para apoiar. Agende uma demo para discutir o seu projecto.