Introdução
No Odoo, os modelos são a forma como os dados são estruturados e guardados na base de dados. Tudo o que representa informação operacional — encomendas, faturas, contactos — vive dentro de um modelo específico.
Saber como funcionam os modelos é crucial tanto para programadores como para consultores funcionais. São o alicerce da arquitetura de dados do Odoo: determinam campos, relações e regras de negócio.
Este artigo aborda um dos modelos mais usados no módulo Vendas: o sale.order.line. Se estiver a criar módulos customizados, a integrar sistemas externos ou a definir regras de preços, vai cruzar-se constantemente com este modelo.
O que é o modelo sale.order.line
O sale.order.line representa cada artigo numa proposta ou encomenda de venda. Cada registo corresponde normalmente a um produto, com quantidade, preço e impostos associados.
Este modelo pertence ao módulo sale e herda funcionalidades que permitem ligação com projetos e tracking analítico. Sempre que adiciona um produto a uma proposta, está a gerar um registo sale.order.line.
O modelo é definido no módulo base de Vendas e é habitualmente estendido por outros módulos via herança de modelos. Por exemplo, módulos de stock acrescentam campos de entrega; módulos de margem acrescentam cálculos financeiros — tudo sem duplicar a estrutura principal.
Campos principais do modelo
A seguir ficam os campos mais relevantes do sale.order.line. Compreender estes campos facilita a configuração de propostas, entregas e faturação.
1. order_id
Tipo: Many2one (sale.order). Obrigatório. Ligação à encomenda pai. Cada linha referencia a sua encomenda e é eliminada em cascata se a encomenda for apagada.
2. sequence
Tipo: Inteiro. Valor por defeito 10. Define a ordem de apresentação das linhas — útil para ordenar secções, notas e artigos.
3. company_id
Tipo: Many2one (res.company). Relacionado a partir de order_id. Usado em regras multiempresa e controlo de acessos.
4. currency_id
Tipo: Many2one (res.currency). Relacionado a partir de order_id. Determina a moeda utilizada para os valores monetários da linha.
5. order_partner_id
Tipo: Many2one (res.partner). Relacionado a partir de order_id. O cliente associado; influencia listas de preços e impostos.
6. salesman_id
Tipo: Many2one (res.users). Relacionado a partir de order_id. Identifica o vendedor para comissões e relatórios.
7. state
Tipo: Selection. Relacionado a partir de order_id. Estado da encomenda (rascunho, enviado, vendido, concluído, cancelado) e determina edição de campos.
8. display_type
Tipo: Selection. Valores: line_section ou line_note. Indica que a linha é um cabeçalho de secção ou uma nota, não um artigo — campos de produto ficam vazios.
9. is_downpayment
Tipo: Boolean. Sinaliza se a linha é um adiantamento. Adiantamentos são faturados à parte.
10. is_expense
Tipo: Boolean. Verdadeiro quando a linha provém de uma despesa ou fatura de fornecedor, útil para rastreio de custos por projeto.
11. product_id
Tipo: Many2one (product.product). Produto a vender. O domínio restringe a artigos vendáveis — obrigatório para linhas de produto.
12. product_template_id
Tipo: Many2one (product.template). Calculado a partir de product_id. Utilizado pelo configurador para seleção de variantes.
13. name
Tipo: Text. Descrição da linha. Geralmente construída a partir do produto e atributos personalizados, incluindo detalhes da variante.
14. product_uom_qty
Tipo: Float. Obrigatório. Quantidade encomendada. Valor por defeito 1.0; pode ser influenciada por embalagens.
15. product_uom
Tipo: Many2one (uom.uom). Unidade de medida. Vem por defeito do produto e afecta quantidade e preços.
16. tax_id
Tipo: Many2many (account.tax). Impostos aplicados à linha. Normas fiscais e posicionamento fiscal podem recalcular estes impostos.
17. price_unit
Tipo: Float. Obrigatório. Preço unitário por unidade de medida. Normalmente calculado via lista de preços, mas pode ser alterado manualmente.
18. discount
Tipo: Float. Percentagem de desconto aplicada ao price_unit antes dos impostos.
19. price_subtotal
Tipo: Monetary. Subtotal antes de impostos. Calculado a partir de quantidade, preço unitário e desconto.
20. price_tax
Tipo: Float. Valor total dos impostos. Calculado a partir do subtotal e dos impostos aplicáveis.
21. price_total
Tipo: Monetary. Total com impostos. Valor principal para efeitos de faturação.
22. product_packaging_id
Tipo: Many2one (product.packaging). Embalagem opcional (ex.: caixa de 12). Quando presente, pode condicionar quantidades.
23. customer_lead
Tipo: Float. Tempo de entrega em dias — intervalo entre confirmação da encomenda e expedição, usado no cálculo das datas de entrega.
24. qty_delivered
Tipo: Float. Quantidade entregue. Atualizado por movimentos de stock ou manualmente; serve para faturação parcial.
25. qty_invoiced
Tipo: Float. Quantidade já faturada. Calculado a partir das linhas de fatura associadas.
26. qty_to_invoice
Tipo: Float. Quantidade pendente de faturação. Calculado a partir de qty_delivered e qty_invoiced.
27. invoice_status
Tipo: Selection. Valores: upselling, invoiced, to invoice, no. Indica o estado de faturação da linha.
28. invoice_lines
Tipo: Many2many (account.move.line). Liga às linhas de fatura geradas a partir desta linha de venda para rastreabilidade.
29. create_date
Tipo: Datetime. Data de criação do registo. Gerido automaticamente pelo Odoo.
30. write_date
Tipo: Datetime. Data da última alteração. Útil para auditoria e sincronização.
Como este modelo entra nos processos de negócio
1. Proposta e encomenda de venda
Ao criar uma proposta, o vendedor adiciona artigos que geram linhas no pedido. Cada linha mostra quantidade, preço, desconto e total; a proposta passa a encomenda quando o cliente confirma.
2. Listas de preços e descontos
As regras de preço aplicam-se por linha: price_unit e discount são calculados a partir das regras da lista de preços. Descontos por volume ou preços por cliente são geridos aqui.
3. Entrega e faturação
Quando o stock é expedido, qty_delivered é atualizada. A faturação pode ser feita por entrega ou em bloco; invoice_status ajuda a identificar o que falta faturar.
4. Projetos e serviços
Para serviços, as linhas podem ligar-se a tarefas e folhas de horas. A herança analítica permite atribuir custos e receitas a projetos específicos.
5. E‑commerce e portal
No site, cada linha do carrinho converte-se numa sale.order.line quando o pedido é criado. O configurador de produtos usa product_template_id e atributos para escolher variantes.
Como os programadores expandem este modelo
Os programadores estendem o sale.order.line através de padrões estabelecidos no Odoo, sendo a herança de modelos o método mais comum.
Herança de modelos
Defina _inherit = 'sale.order.line' no seu módulo para acrescentar campos, sobrepor métodos ou adicionar restrições. Manter as alterações num módulo separado facilita actualizações.
Adicionar campos
Declare novos campos no modelo herdado usando o tipo adequado: Char, Many2one, Boolean, Integer, Text, Selection, etc. Pense em campos dependentes da empresa para ambientes multiempresa.
Extensões em Python
Sobreponha compute methods como _compute_price_unit ou _compute_price_subtotal, ou implemente lógica em create/write. Use super() para preservar o comportamento base e tenha atenção às dependências de campos computados.
Odoo Studio
O Odoo Studio permite adicionar campos sem programar, ideal para ajustes rápidos. Para lógica complexa ou manutenção a longo prazo, prefira módulos personalizados.
Boas práticas
- Use display_type para inserir secções e notas em vez de linhas‑“falsas” de produto — assim evita ruído nos relatórios e validações.
- Ao integrar via API, crie as linhas no contexto da encomenda. Use order_line_ids no sale.order com o formato de comandos correcto para manter integridade relacional.
- Respeite as constraints SQL: linhas de produto exigem product_id e product_uom; secções e notas devem ter display_type definido.
- Para regras de preço personalizadas, prefira listas de preços. Só altere os cálculos centrais quando a lógica necessária não for suportada pelas listas.
- Ao criar campos personalizados, prefixe com x_ ou utilize um prefixo do módulo para evitar colisões com futuras versões do Odoo.
Erros frequentes
- Criar linhas sem order_id. Este campo é obrigatório — crie sempre linhas no contexto de uma encomenda para evitar registos órfãos.
- Confundir product_id com product_template_id. Para linhas de produto, use product_id; para fluxos de configurador que escolhem variantes, trabalhe com product_template_id.
- Alterar price_unit ou discount após faturação. Quando qty_invoiced > 0, mudar preços pode causar inconsistências contabilísticas.
- Sobrepor métodos core sem chamar super(). Isto pode quebrar funcionalidades de outros módulos e dificultar futuras actualizações.
- Esquecer display_type em linhas de secção ou nota. Sem ele, a linha será tratada como produto e falhará nas validações.
Conclusão
O modelo sale.order.line é um pilar das Vendas no Odoo: guarda cada linha de produto nas propostas e encomendas. Conhecer os seus campos e como os módulos o estendem ajuda a configurar, customizar e integrar o Odoo com segurança.
Quer seja um consultor a desenhar processos ou um programador a desenvolver módulos, dominar o sale.order.line evita erros e acelera implementações.
Precisa de ajuda com a sua implementação Odoo?
A Dasolo ajuda empresas a implementar, adaptar e optimizar Odoo. Temos experiência em integrações via API e desenvolvimento à medida, com conhecimento profundo da arquitectura de dados e modelos como o sale.order.line.
Se precisa de apoio na sua implementação Odoo, criação de módulos personalizados ou integrações, colocamo‑nos à disposição. Agende uma demonstração para discutir o seu projecto.