«AN26000001» diz mais do que «S00001»: é um orçamento, é de 2026 e é o primeiro. Muitas empresas, sobretudo as que passam de um sistema mais antigo para o Odoo, querem manter os seus números de documento exatamente assim. O próprio Odoo numera orçamentos, encomendas e guias de remessa com sequências próprias (S00001, WH/OUT/00001, P00001) e as faturas com o prefixo do diário e o ano (INV/2026/00001).
Para isso escrevemos o módulo Document Numbering by Prefix and Year (document_number_prefix_year) para o Odoo 19. Está disponível no GitHub como software livre sob a licença LGPL-3:
github.com/Alex0176/odoo-document-number-prefix-year
Uma classificação honesta, desde já: na Biricon IT Services não utilizamos este módulo. Publicamo-lo porque está concluído, documentado e dotado de testes, e pode poupar trabalho a outros. Quem o utilizar deve ler as secções sobre Limitações e Testes .
O esquema de numeração
Cada número é composto por três partes: um prefixo por tipo de documento, o ano e um contador com um número fixo de dígitos. O prefixo, o formato do ano (26 ou 2026) e o número de dígitos definem-se por empresa em Definições → Numeração de documentos.
São tratados os orçamentos, as encomendas de clientes, as faturas e notas de crédito de clientes, as guias de remessa, as entradas de mercadorias e as encomendas de compra. Os prefixos na figura são apenas exemplos: AN, AU, RE, GU, LI, WE, BE. Quem deixar um prefixo vazio mantém, para esse tipo de documento, a numeração padrão do Odoo. O módulo não faz, portanto, nada até que o configure.
Como se comportam os números
- Novo em cada ano. O contador recomeça em 1 com a mudança de ano.
- Continuar a partir dos números importados. O módulo procura o número mais alto existente com o mesmo prefixo e ano, independentemente do seu comprimento. Se o sistema antigo deixou
AN26119na base de dados, o orçamento seguinte seráAN26000120. É por isso que o módulo serve para migrações: os documentos antigos são importados com os seus números originais, e os novos documentos continuam sem rutura. - Novo número de encomenda na confirmação. Um orçamento confirmado recebe, se desejado, um número da sequência de encomendas. O número do orçamento é mantido no campo Número do orçamento na encomenda e é visível no formulário, na lista e na pesquisa.
- Faturas ao lançar. As faturas e notas de crédito de clientes só recebem o número ao serem lançadas, não ao serem criadas. Os rascunhos eliminados não deixam, por isso, lacunas. O ano provém da data da fatura: uma fatura de 30.12.2025 que seja lançada a 2.1.2026 chama-se
RE25…. - Tudo o resto fica igual. As faturas de fornecedores, os pagamentos, os lançamentos contabilísticos e as ordens de fabrico mantêm as sequências padrão do Odoo. Os nomes existentes nunca são reescritos, nem mesmo que volte a desativar o módulo.
A parte delicada: dois utilizadores em simultâneo
Uma atribuição de números própria parece simples: procurar o número mais alto e somar um. Deixa de o ser quando dois utilizadores criam um orçamento no mesmo instante. Ambos leem «número mais alto = 0», ambos atribuem AN26000001. O Odoo tem, para as suas próprias sequências, sequências de base de dados. Num número construído por nós isso não existe e, para orçamentos e encomendas de compra, o Odoo não tem sequer verificação de unicidade no nome: dois documentos com o mesmo número são simplesmente guardados.
A proteção mais óbvia é um bloqueio. O módulo adquire, por empresa, prefixo e ano, um bloqueio da base de dados (PostgreSQL Advisory Lock), que se mantém até ao fim da transação. O segundo utilizador espera até o primeiro terminar. Mas isso não basta, e descobrimo-lo com uma experiência numa cópia da base de dados de produção:
O Odoo trabalha com o nível de isolamento REPEATABLE READ. O estado da base de dados que uma transação vê é congelado na sua primeira consulta. O utilizador B já tem este estado antes de A terminar. Se B esperar depois pelo bloqueio e o obtiver, lê, com o seu estado antigo, «número mais alto = 0» e atribui o número uma segunda vez. O bloqueio regulou a ordem, mas não atualizou o conhecimento.
A solução é uma segunda leitura através de um acesso próprio e de curta duração à base de dados, que vê todas as linhas já confirmadas. Ganha o maior dos dois valores. A primeira leitura continua a ser necessária, pois só ela conhece os números que a mesma transação já atribuiu mas ainda não confirmou, por exemplo na importação de vários documentos de uma só vez.
Verificámo-lo com duas transações, nas quais a segunda comprovadamente obteve o seu estado antes do commit da primeira e depois esperou pelo bloqueio. Sem a segunda leitura, ambas as encomendas receberam o mesmo número; com ela, os números 1 e 2.
Importante para o enquadramento: esta experiência é uma verificação manual. Não faz parte dos testes automáticos, porque para isso são necessárias duas ligações reais à base de dados, que o ambiente de testes do Odoo (uma única transação por teste) não disponibiliza.
Implementação técnica
| Documento | Ponto de integração |
|---|---|
| Orçamento | sale.order.create, quando o nome está vazio, é / ou New |
| Encomenda de cliente | sale.order.action_confirm, antes da confirmação padrão |
| Fatura, nota de crédito | account.move._set_next_sequence, é invocado ao lançar |
| Guia de remessa, entrada de mercadorias | stock.picking.create por tipo de operação |
| Encomenda de compra | purchase.order.create |
- Contador. O número mais alto é encontrado por uma expressão regular (
^<raiz>([0-9]{1,15})$, a raiz é escapada) por empresa, incluindo nomes sem empresa. - Faturas.
_set_next_sequenceescreve o nome e invoca_compute_split_sequence, para que a lógica de sequência do Odoo (prefixo, número, deteção do ano para a próxima fatura do diário) se mantenha coerente. - Definições. Os campos da empresa
document_number_*são espelhados emres.config.settings. As definições rejeitam prefixos com espaços ou com um algarismo no fim. - Tradução. Inclui tradução alemã.
Instalação e configuração
- Colocar a pasta
document_number_prefix_yearno caminho dos addons. - Atualizar a lista de aplicações, instalar o módulo. São requisitos Vendas, Compras, Inventário e Contabilidade.
- Em Definições → Numeração de documentos, introduzir prefixos, formato do ano e número de dígitos.
- Experimente primeiro numa cópia. O número de um documento não pode ser revertido automaticamente mais tarde e, no caso das faturas, ao número associam-se obrigações de conservação e de verificação.
Limitações
- Os orçamentos são numerados na criação. Os orçamentos eliminados ou cancelados deixam lacunas. O mesmo vale para qualquer encomenda de cliente criada por outro módulo: os carrinhos de compras da loja online (
website_sale) são encomendas no estado Orçamento e consomem um número cada. Só as faturas e notas de crédito não têm lacunas, porque são numeradas ao lançar. - Não alterar o formato do ano em plena operação. Com a raiz
AN26, o módulo lê umAN2026000001existente como contador26000001. Defina o formato antes do primeiro documento. - Contador com, no máximo, 15 dígitos. As sequências de dígitos mais longas a seguir à raiz são ignoradas na procura do número mais alto.
- Sem séries separadas por diário ou armazém. O contador aplica-se por empresa, prefixo e ano. Vários diários de vendas partilham o contador de faturas.
- Os prefixos não podem conter espaços nem terminar num algarismo; caso contrário, o prefixo, o ano e o contador já não se conseguem separar.
- Apenas os tipos de documento indicados são tratados.
Testes
O módulo inclui dez testes automáticos. Verificam:
- Orçamento e confirmação: número do orçamento e da encomenda, preservação do número do orçamento
- Continuação a partir de um número importado (
AN26119→AN26000120) - nenhuma renumeração posterior de documentos existentes
- Fatura, nota de crédito e mudança de ano segundo a data da fatura
- Encomenda de compra e guias de remessa
- prefixo vazio: o número padrão do Odoo mantém-se
- ano com quatro dígitos
- prefixo com carateres especiais
- vários números numa transação
- as sequências de dígitos muito longas são ignoradas
Execução:
odoo-bin -d <Testdatenbank> -i document_number_prefix_year --test-enable --test-tags=/document_number_prefix_year --stop-after-initOs testes decorrem com transações normais. O comportamento na criação simultânea por dois utilizadores não faz parte deles; foi verificado manualmente numa cópia da base de dados, como descrito acima. Quem utilizar o módulo num sistema com muitos utilizadores em simultâneo deve repetir esta experiência na sua própria base de dados.
Aviso legal sobre o número da fatura
Nos termos do § 11 UStG, as faturas têm de ter um número sequencial, atribuído uma única vez para identificar a fatura. O módulo numera as faturas ao lançar e com um contador próprio por prefixo e ano, o que é compatível com isso. Se a sua configuração concreta (vários diários, notas de crédito com prefixo próprio, mudança de ano) cumpre os requisitos do seu consultor fiscal, tem de o esclarecer com este. Este artigo não constitui aconselhamento jurídico.
Perguntas frequentes
Porque não simplesmente adaptar as sequências do Odoo?
Para as faturas, isso é possível através do prefixo do diário. Para orçamentos, encomendas, guias de remessa e encomendas de compra, porém, não existe um esquema comum de prefixo, ano e contador com mudança de ano, e o contador não conhece números antigos importados. É aí que o módulo atua.
A numeração existente é substituída?
Não. O módulo só atribui números novos. Os nomes já guardados permanecem inalterados, mesmo ao desativar.
Como o desativo?
Esvazie o prefixo do tipo de documento. Nesse caso, o Odoo volta a numerá-lo por si. Também desinstalar não altera os números atribuídos.
Utilizam-no vocês próprios?
Não. Connosco funcionam os números padrão do Odoo. Verificámos o módulo com os testes automáticos e a experiência manual descrita, mas não numa operação real com muitos utilizadores.
Funciona com o Odoo 17 ou 18?
Testámo-lo apenas com o Odoo 19.0 Community. Para outras versões pode servir ou não; não o verificámos.
Sob que licença está?
Sob a LGPL-3. Erros e melhorias são bem-vindos como issue no repositório GitHub .
Apoio da Biricon IT Services
Damos assistência a instalações Odoo para pequenas e médias empresas: da implementação, passando por adaptações e migrações, até à operação corrente. Se, na migração, quer preservar os seus números de documento, mandar verificar a atribuição de números sob carga ou colocar um módulo como este em segurança na sua instância de produção, teremos todo o gosto em ajudar. Outros desenvolvimentos próprios: Firmenbuch e verificação de moradas para clientes austríacos, Conjuntos de produtos no orçamento como secção e Web RBL, a lista de bloqueio para tráfego de ataque.
Situação em: 3 de novembro de 2026. Versão do módulo 19.0.1.0.0. Todos os números nos exemplos e nas figuras são de livre escolha.