Introdução
No Odoo, os modelos são as plantas que definem como a informação empresarial é organizada e guardada na base de dados. Tudo — encomendas, faturas, lançamentos contabilísticos — assenta numa estrutura de modelo que determina campos, relações e regras de validação.
Compreender os modelos do Odoo é obrigatório tanto para consultores funcionais como para desenvolvedores. São a espinha dorsal da arquitectura de dados: estabelecem campos, ligam registos entre si e encapsulam a lógica de negócio que dá significado aos dados.
Este texto analisa um dos modelos mais críticos na contabilidade do Odoo: account.move. Se estiver a criar relatórios personalizados, a integrar sistemas externos ou a configurar processos de faturação, vai passar bastante tempo a trabalhar com este modelo.
O que é o modelo account.move
O account.move representa os lançamentos contabilísticos. A partir do Odoo 13, este modelo unificou várias entidades anteriores — faturas de clientes, faturas de fornecedores, notas de crédito e lançamentos manuais — colocando tudo numa única tabela lógica: account.move.
O módulo de Contabilidade usa intensamente este modelo. O account.move é pai das linhas (account.move.line), onde ficam os débitos e créditos individuais. Cada fatura, fatura de fornecedor ou lançamento é um registo account.move acompanhado de uma ou várias linhas.
A definição base está no módulo account, e outros módulos acrescentam funcionalidades através da herança de modelos do Odoo. O módulo de Vendas adiciona criação de faturas a partir de encomendas; Compras adiciona criação de facturas a partir de pedidos; cada módulo só estende o núcleo, evitando duplicar a estrutura principal.
Campos-chave do modelo
A seguir estão os campos mais relevantes do account.move. Conhecê-los facilita manipular faturas, recibos e lançamentos e interpretar corretamente relatórios e reconciliações.
1. name
Tipo: Char. Guarda o identificador do lançamento (número ou nome). Normalmente gerado automaticamente pela sequência do diário e visível em listagens e documentos impressos.
2. move_type
Tipo: Selection. Indica o tipo de documento: lançamento manual, fatura cliente, nota de crédito cliente, fatura fornecedor, nota de crédito fornecedor. Este campo determina vistas, validações e fluxos aplicáveis.
3. state
Tipo: Selection. Estado do fluxo: draft (rascunho), posted (lançado) ou cancel (anulado). Em rascunho é editável; em lançado influencia o razão-geral e fica protegido.
4. date
Tipo: Date. Data do documento. Relevante para relatórios, ageing e encerramentos. Nas faturas, costuma ser a data de emissão.
5. journal_id
Tipo: Many2one (account.journal). Diário a que o lançamento pertence — vendas, compras, caixa, banco, etc. O diário determina sequência e contas por defeito.
6. company_id
Tipo: Many2one (res.company). Em ambientes multiempresa identifica a empresa responsável pelo lançamento, influenciando visibilidade e consolidação.
7. partner_id
Tipo: Many2one (res.partner). Cliente ou fornecedor associado. Obrigatório para faturas e usado em relatórios de vencimentos, conciliações e cabeçalhos de documentos.
8. currency_id
Tipo: Many2one (res.currency). Moeda do lançamento. Os valores são armazenados nesta moeda; para relatórios multicurrency há conversões para a moeda da empresa.
9. amount_total
Tipo: Monetary. Valor total do lançamento. Numa fatura, representa o montante a pagar. É calculado a partir das linhas.
10. amount_residual
Tipo: Monetary. Montante em aberto. Para faturas pagas é zero. Serve para ageing, notificações de pagamento e reconciliações.
11. payment_state
Tipo: Selection. Estado do pagamento: not_paid, in_payment, paid, partial, reversed, etc. Influencia lembretes, ações automáticas e relatórios de tesouraria.
12. line_ids
Tipo: One2many (account.move.line). Linhas do lançamento. Cada linha tem conta, débito e crédito; o total de débitos deve igualar o total de créditos.
13. invoice_line_ids
Tipo: One2many (account.move.line). Linhas de fatura (produtos ou serviços). Ao validar, cada linha de fatura gera uma ou mais linhas contabilísticas.
14. invoice_date
Tipo: Date. Data da fatura, usada para efeitos de faturação e fiscais; pode diferir da data do lançamento em configurações específicas.
15. invoice_date_due
Tipo: Date. Data de vencimento do pagamento. Calculada a partir das condições de pagamento ou definida manualmente; usada em ageing e cobrança.
16. ref
Tipo: Char. Referência externa — por exemplo o número do documento do fornecedor. Útil para conciliações e cruzamento com documentos externos.
17. invoice_origin
Tipo: Char. Origem do documento. Quando a fatura provém de uma encomenda, aqui fica o número da SO, garantindo rastreabilidade entre encomenda e fatura.
18. create_date
Tipo: Datetime. Data e hora de criação do registo — gerido automaticamente pelo Odoo.
19. write_date
Tipo: Datetime. Data e hora da última alteração — também gerido automaticamente.
20. narration
Tipo: Text. Notas internas ou memos exibidos em lançamentos impressos; normalmente não aparecem para o cliente nas faturas.
21. fiscal_position_id
Tipo: Many2one (account.fiscal.position). Posição fiscal que determina regras de impostos conforme parceiro e país.
22. invoice_payment_term_id
Tipo: Many2one (account.payment.term). Condições de pagamento (ex.: 30 dias). Usadas para calcular data de vencimento e dividir pagamentos.
23. invoice_user_id
Tipo: Many2one (res.users). Utilizador responsável pela fatura — frequentemente o vendedor; serve para comissões e relatórios.
24. reversed_entry_id
Tipo: Many2one (account.move). Quando um lançamento é anulado, este campo aponta para o lançamento que reverteu o original — útil para auditoria.
25. to_check
Tipo: Boolean. Indicador para movimentos que necessitam de revisão — usado em conciliação bancária e fluxos de exceção.
26. active
Tipo: Boolean. Indicador de arquivamento (soft delete). Quando False, o registo fica arquivado; lançamentos cancelados costumam ficar desactivados.
27. sequence_number
Tipo: Integer. Número de sequência do diário, usado para ordenação e apresentação — gerido pelo mecanismo de sequências.
28. amount_untaxed
Tipo: Monetary. Subtotal antes de impostos. Nas faturas corresponde à soma das linhas sem impostos.
29. amount_tax
Tipo: Monetary. Total de impostos. Calculado a partir das linhas de fatura e da configuração fiscal.
30. invoice_source_email
Tipo: Char. Quando facturas de fornecedores são criadas por email, este campo guarda o remetente — útil para ingestão automática de faturas por email.
Como este modelo entra nos fluxos de trabalho
1. Faturação a clientes
Quando uma encomenda de venda é entregue, o Odoo cria um account.move com move_type out_invoice e preenche invoice_line_ids a partir das linhas da encomenda. Ao validar, geram‑se as linhas contabilísticas e actualizam‑se as contas a receber.
2. Faturas de fornecedores
Os pedidos de compra podem gerar faturas automaticamente ou estas são introduzidas manualmente. Cada fatura fica como account.move com move_type in_invoice e, ao validar, actualiza as contas a pagar do fornecedor.
3. Conciliação de pagamentos
Os pagamentos são ligados às faturas com base em amount_residual e payment_state. O processo de conciliação associa movimentos de pagamento aos movimentos de fatura e reduz o residual até o registo ficar liquidado.
4. Lançamentos manuais
Os contabilistas criam lançamentos com move_type entry para ajustes, provisões ou correcções, adicionando manualmente line_ids com contas, débitos e créditos. O lançamento deve ficar equilibrado antes de ser lançado.
5. Notas de crédito e reembolsos
As notas de crédito surgem como move_type out_refund ou in_refund e invertem o efeito da fatura original. O campo reversed_entry_id liga à fatura original, mantendo a pista de auditoria.
Como os programadores estendem este modelo
Os programadores ampliam o account.move com vários padrões de personalização, tendo a herança de modelo do Odoo como ferramenta principal.
Herança de modelo
Defina _inherit = 'account.move' no seu módulo para adicionar campos, sobrescrever métodos ou impor novas restrições. A herança mantém alterações separadas do núcleo, facilitando atualizações e manutenção.
Adicionar campos
Declare novos campos no modelo herdado usando os tipos adequados: Char, Many2one, Boolean, Integer, Text, Selection. Em contextos multiempresa considere campos dependentes da empresa e use domínios para limitar campos a tipos de movimento específicos.
Extensões em Python
Sobrescreva métodos como create, write, _post ou button_draft para inserir lógica adicional, chamando super() quando necessário. Preste atenção a campos computados e às suas dependências; os decoradores @api.model e @api.depends determinam quando as funções são executadas.
Odoo Studio
O Odoo Studio permite adicionar campos sem programar, ideal para ajustes rápidos como campos de referência. Para lógica complexa, validações ou automações, é preferível um módulo personalizado bem desenhado.
Nota: account.move é um modelo persistente — não é abstract nem transient. Modelos abstract são templates sem tabela na BD; transient servem wizards temporários. account.move guarda dados contabilísticos permanentes e auditáveis.
Boas práticas
- Ao criar relatórios ou integrações, filtre sempre pelo move_type: cada tipo de movimento exige campos e comportamentos diferentes.
- Use o diário (journal) apropriado para cada tipo de lançamento. Misturar diários pode invalidar sequências e corromper relatórios.
- Ao criar lançamentos via API, assegure-se de que line_ids estão balanceadas (débitos = créditos) antes de postar. Lançamentos desequilibrados são rejeitados pela validação.
- Ao importar faturas de sistemas externos, mapeie corretamente os tipos de documento para move_type: out_invoice para vendas e in_invoice para compras.
- Adote o prefixo x_ nos campos personalizados para evitar colisões com futuras versões do Odoo.
Erros comuns
- Publicar lançamentos com linhas desequilibradas. Odoo não permitirá a validação — confirme sempre que débitos e créditos coincidem.
- Alterar directamente lançamentos já lançados. Registos em estado posted estão bloqueados; utilize lançamentos de reversão para corrigir e evitar inconsistências.
- Esquecer de preencher partner_id em movimentos de cliente/fornecedor. Muitas funções, relatórios e conciliações dependem deste campo.
- Usar um move_type errado. Uma out_refund não é a mesma coisa que uma out_invoice negativa — use o tipo adequado para notas de crédito e reembolsos.
- Sobrescrever métodos do núcleo sem chamar super(). Isso pode quebrar compatibilidades com outros módulos e complicar upgrades futuros.
Conclusão
O account.move é o eixo central da contabilidade no Odoo: unifica faturas, notas e lançamentos numa estrutura consistente. Dominar os seus campos e como outros módulos o estendem facilita configurações, personalizações e integrações seguras.
Quer seja um consultor a modelar processos ou um desenvolvedor a construir módulos, conhecer bem o account.move poupa tempo, reduz erros e melhora a qualidade das implementações.
Precisa de ajuda com o seu Odoo?
A Dasolo acompanha empresas na implementação, personalização e optimização do Odoo. Somos especialistas em integrações via API e desenvolvimento de módulos, com experiência profunda na arquitectura de dados do Odoo e em modelos como o account.move.
Se precisa de apoio na sua implementação Odoo, desenvolvimento de módulos ou integrações, estamos disponíveis para ajudar. Agende uma demonstração para discutirmos o seu projecto.