Numeração de Documentos e Séries Documentais no ERP

# Séries Documentais e Numeração: A Regra Invisível que Bloqueia Módulos Inteiros

TL;DR: Se um tipo de documento não tem uma série activa correctamente configurada, o módulo que o emite não falha com um erro — simplesmente não mostra nada para criar, porque a query que gera o formulário depende de uma série que não existe. O desenho da numeração não é um detalhe administrativo: é uma pré-condição estrutural para o módulo funcionar, e está ligado a uma exigência fiscal concreta em Angola — numeração sequencial e cronológica, sem lacunas.

O sintoma: um ecrã vazio, não uma mensagem de erro

Há um padrão de falha que se repete em sistemas de gestão sempre que alguém tenta activar um módulo novo — uma nova filial, um novo tipo de nota de crédito, um novo estabelecimento de facturação: o botão "Criar" está lá, o formulário carrega, mas ao submeter nada acontece, ou o campo do número do documento aparece vazio, ou a lista de séries disponíveis está em branco. Não há excepção, não há stack trace, não há mensagem "série não encontrada". Do ponto de vista do utilizador, o módulo simplesmente não funciona.

A causa raiz quase nunca está na lógica de negócio do módulo. Está uma camada abaixo: o tipo de documento em questão (factura, nota de crédito, guia de remessa, requisição de material, ordem de compra) não tem uma série documental activa associada, para aquele estabelecimento, para aquele ano fiscal. Sem série, não há de onde tirar o próximo número. Sem número, o registo não pode ser criado — porque, tipicamente, o número do documento faz parte da chave que o torna válido, tanto para o sistema como, em Angola, para a Administração Geral Tributária (AGT).

Isto é agravado pelo facto de a numeração de documentos raramente aparecer nos requisitos funcionais de um módulo novo. Quem desenha o ecrã de "Nova Requisição de Material" pensa em campos, aprovações, centros de custo — não pensa que, sem uma entrada na tabela de séries, esse ecrã nunca vai conseguir gravar nada. É um requisito estrutural, não funcional, e por isso é fácil de esquecer até ao dia em que alguém tenta usar o módulo em produção.

O que é, tecnicamente, uma série documental

Uma série documental é, na prática, um contador com regras. Define-se por um conjunto de atributos: um tipo de documento, um prefixo (ou identificador) único, um âmbito (normalmente o ano civil, por vezes o estabelecimento ou entidade emissora) e um número sequencial que avança de forma monotónica e sem retrocessos dentro desse âmbito. Em Angola, a lei exige "numeração sequencial e cronológica por tipo de documento e o respectivo ano económico, podendo ser utilizadas uma ou mais séries devidamente identificadas" (art. 10.º, n.º 1, alínea b) do Decreto Presidencial n.º 71/25). Na prática dos fornecedores de software de facturação, cria-se uma série por ano com o ano no nome — numa série "2025A", a primeira factura sai como "2025A/1" (WISEDAT).

No desenho de dados de um ERP, isto tipicamente materializa-se numa tabela DocumentSeries (ou equivalente) com colunas como documentType, prefix, fiscalYear, establishmentId, currentNumber e isActive, referenciada por chave estrangeira a partir de cada tabela de documento (Invoice, CreditNote, PurchaseOrder, MaterialRequisition). O erro de desenho mais comum é tratar essa referência como opcional — permitir que seriesId seja nulo "por enquanto", com a intenção de o preencher mais tarde. Isso resolve o problema de curto prazo de conseguir arrancar o desenvolvimento do módulo, mas transfere o problema para produção: no dia em que um utilizador de negócio tenta emitir o primeiro documento de um tipo novo, não há série, não há número, e o ecrã fica vazio.

A base legal: numeração sequencial, cronológica e sem lacunas

Em Angola, a emissão de facturas e documentos equivalentes é regulada pelo Regime Jurídico das Facturas e Documentos Equivalentes (RJFDE), aprovado originalmente pelo Decreto Presidencial n.º 292/18, de 3 de Dezembro, em vigor desde 2 de Abril de 2019. Esse diploma foi revogado pelo Decreto Presidencial n.º 71/25, de 20 de Março de 2025 (art. 40.º), que aprova o novo Regime Jurídico das Facturas e entrou em vigor seis meses após a publicação, a 20 de Setembro de 2025 (art. 42.º) (Angolex — Decreto 71/25; Angolex — Decreto 292/18). A regra de numeração atravessou a mudança: estava no artigo 11.º do diploma de 2018 e está hoje no artigo 10.º, n.º 1, alínea b) do DP 71/25 — numeração sequencial e cronológica por tipo de documento e ano económico (EY Angola).

Na prática operacional, isto significa três coisas para quem desenha o sistema:

1. O software de facturação certificado tem de garantir numeração sequencial e cronológica e impedir a eliminação de documentos depois da emissão (é assim que o art. 3.º do DP 71/25 define "Software de Facturação") — não pode existir um caminho de código, mesmo administrativo, que apague um número já atribuído sem deixar rasto.

2. A sequência reinicia por ano económico e por tipo de documento, o que na prática obriga a criar séries novas no arranque de cada ano (com o ano no identificador, como "2026A") — o sistema tem de tratar o ano como parte do âmbito da série, não como um detalhe de apresentação.

3. O contribuinte tem de comunicar à AGT, por via electrónica, a identificação de cada série usada e não usada (art. 24.º, n.º 1, alínea c)). E a consequência de falhar é pesada: as facturas cujas séries não tenham sido comunicadas consideram-se não emitidas (art. 35.º, n.º 4), o que atrai as coimas por falta de emissão de factura — 7% do valor da factura, 15% em caso de incumprimento reiterado (art. 35.º, n.º 1). A série não é, portanto, um artefacto interno do sistema — é uma entidade que tem de ser declarada e reconciliável com o que a autoridade tributária tem registado.

Esta ligação entre numeração e obrigação fiscal é o motivo pelo qual "ecrã vazio" é, na verdade, o comportamento correcto do sistema quando não há série válida — mesmo que a mensagem de erro devesse ser mais explícita. Um sistema bem desenhado nunca deveria permitir que um utilizador crie um número de documento fora de uma série declarada, porque isso criaria exactamente o tipo de lacuna que a lei proíbe. O ponto fraco não é a regra; é a ausência de uma mensagem clara quando a regra bloqueia a operação. Este é também o pano de fundo que torna a facturação electrónica obrigatória em Angola tão sensível à forma como as séries são desenhadas: se a série que alimenta a factura electrónica não estiver correctamente configurada, o problema propaga-se directamente à comunicação com a AGT.

O prefixo tem limite — e o limite obriga a abreviar

Há uma restrição técnica concreta que raramente é discutida antes de se tornar um problema: o identificador composto que junta tipo de documento, código interno e série tem um comprimento máximo. A especificação técnica do SAF-T (AO) — o ficheiro normalizado de auditoria fiscal que as empresas em Angola submetem à AGT — define os campos InvoiceNo e DocumentNumber com um limite de 60 caracteres e um padrão obrigatório no formato [Tipo de Documento] [Código Interno]/[Número Sequencial] (SAF-T AO XSD, `SAFTAO1.01_01.xsd`, publicado pela ASSOFT no GitHub). Os exemplos do próprio esquema são curtos: FT S001/1, NC S001/1.

Sessenta caracteres parecem uma folga generosa — até se decompor o que tem de caber lá dentro: o tipo de documento (por exemplo "FT" para factura, "NC" para nota de crédito), um espaço obrigatório, o código interno atribuído pela aplicação ao tipo de documento, o identificador da série, uma barra, e finalmente o número sequencial, que numa operação com volume alto pode ter seis ou sete dígitos ao fim de alguns anos. Se o nome lógico de uma série for algo como "REQUISICAO-MATERIAL-ARMAZEM-LUANDA-2026", simplesmente não cabe. O resultado prático é que quem desenha as séries é forçado a abreviar — "RM-LDA-2026" em vez do nome descritivo — e essa abreviação tem de ser decidida uma vez, de forma consistente, antes de a série entrar em uso, porque mudar o prefixo de uma série activa a meio do ano quebra a continuidade que a lei exige.

Isto tem uma implicação directa no desenho da tabela DocumentSeries: o campo prefix não deve ser um varchar sem restrição — deve ter um limite explícito (tipicamente entre 4 e 12 caracteres, deixando margem para o resto do identificador composto) validado no momento da criação da série, não descoberto mais tarde quando a exportação SAF-T falha a validação do esquema. Detectar isto em produção, no dia da submissão mensal do ficheiro, é muito mais caro do que validar o comprimento no formulário de criação de série.

Como desenhar séries documentais para não bloquear módulos

Um desenho robusto separa três preocupações que é tentador misturar: a definição da série, a atribuição atómica do próximo número, e a validação de que a série existe antes de o ecrã sequer ser desenhado.

Preocupação	O que garantir
Definição da série	Uma série por tipo de documento, por entidade emissora, por ano fiscal; prefixo validado quanto ao comprimento; campo `isActive` explícito
Atribuição do número	Incremento atómico (transacção com `SELECT ... FOR UPDATE` ou sequência dedicada da base de dados) — nunca calcular "máximo + 1" em memória, sob pena de colisões sob concorrência
Disponibilidade para o utilizador	O ecrã de criação do documento verifica a existência de série activa antes de renderizar o formulário, e mostra uma mensagem explícita — "Não existe série activa para Nota de Crédito em 2026" — em vez de um formulário vazio

A atribuição atómica merece atenção especial em ambientes com múltiplos utilizadores a emitir documentos em simultâneo — típico num armazém ou numa base de operações offshore com vários turnos a lançar requisições ao mesmo tempo. Ler o número mais alto e somar um, sem bloqueio, é a forma mais comum de produzir dois documentos com o mesmo número — exactamente a lacuna que a numeração sequencial existe para impedir. A alternativa correcta é uma sequência gerida pela base de dados, ou uma transacção que bloqueia a linha da série até ao commit.

Vale também considerar que, num grupo com várias empresas a partilhar a mesma instância do sistema, cada entidade legal precisa da sua própria numeração — não é possível partilhar uma série entre duas pessoas colectivas distintas, porque a obrigação de sequência sem lacunas é por contribuinte. Este é um dos pontos onde o desenho de séries se cruza directamente com a forma como se modela multi-entidade numa base de dados PostgreSQL partilhada: a série tem de ser isolada por companyId com a mesma disciplina com que se isola qualquer outro dado sensível a fugas entre entidades.

Auditoria: como provar que não há lacunas

Uma série bem desenhada não é apenas uma fonte de números — é uma estrutura que permite responder, a qualquer momento e sem reconciliação manual, à pergunta "existe algum número em falta nesta série?". Isso reduz-se a uma query simples sobre a sequência de números emitidos por série: comparar o número de documentos existentes com a diferença entre o primeiro e o último número, agrupado por série e ano. Uma diferença indica uma lacuna — documento anulado sem sucessor válido, erro de importação, ou pior, uma falha de concorrência na atribuição de números.

Esta é precisamente a lógica que sustenta a extracção do ficheiro SAF-T (AO) sem reconciliações manuais: se a integridade da numeração for garantida na origem, ao nível da transacção que cria o documento, a exportação para SAF-T é uma projecção directa dos dados — não um exercício de detective a meio da submissão mensal.

Perguntas frequentes

O que acontece se eu apagar uma factura com número já atribuído?

Em conformidade com o RJFDE, o software de facturação certificado deve impedir a eliminação de documentos depois da emissão. A prática correcta, quando um documento está errado, é emitir uma nota de crédito ou um documento de anulação que referencia o número original — nunca apagar a linha, porque isso criaria uma lacuna na sequência.

Posso reutilizar a mesma série de um ano para o outro?

Não é o caminho seguro. A numeração é sequencial e cronológica por tipo de documento e ano económico (art. 10.º do DP 71/25), e a prática corrente do software certificado é criar uma série nova em cada ano, com o ano no identificador (por exemplo "2026A"). No arranque de cada ano fiscal é preciso criar e comunicar à AGT as novas séries para os tipos de documento em uso.

Porque é que o meu módulo de requisições de material não deixa criar nada, mesmo sem mensagem de erro?

É o sintoma descrito neste artigo: provavelmente não existe uma série activa configurada para esse tipo de documento no estabelecimento e ano correntes. Vale a pena verificar directamente a tabela de séries antes de assumir um defeito na lógica de negócio do módulo.

Isto aplica-se só a facturas, ou também a documentos internos como requisições e ordens de compra?

A obrigação legal de numeração sequencial sem lacunas, tal como descrita no RJFDE, aplica-se a facturas e documentos fiscalmente equivalentes. Mas o padrão de desenho — série activa como pré-condição para o módulo funcionar — é útil para qualquer documento que precise de um identificador único e auditável, mesmo quando não há uma exigência fiscal directa por trás.

Uma nota sobre quem escreve isto

A Wise Hustlers desenvolve o Enerxia, o seu ERP para o sector petrolífero angolano, com módulos que cobrem upstream, poços, produção, projectos e contratos, procurement, fornecedores, inventário, MRO, manutenção, frota, logística, HSE, qualidade, RH, formação, finanças, fiscalidade e conformidade — incluindo o módulo de séries documentais e numeração que sustenta a facturação e os documentos internos descritos acima. Quando uma equipa precisa de um sistema à medida onde este tipo de regra estrutural é tratado desde o desenho de dados, e não como um patch depois de o módulo já estar em produção, é o tipo de trabalho que fazemos em desenvolvimento de software à medida.

Séries Documentais e Numeração: A Regra Invisível que Bloqueia Módulos Inteiros