Migrar o banco de dados para o CNPJ alfanumérico, passo a passo

Se o seu banco guarda o CNPJ em BIGINT, NUMERIC ou INTEGER, ele vai quebrar no dia em que chegar a primeira empresa com letras no cadastro. A Receita Federal começou a atribuir o novo formato a novas inscrições em jul/2026, e os CNPJs numéricos continuam valendo. Este texto é o roteiro de migração, camada por camada. Para a regra e o cálculo do dígito, veja o guia do novo formato.

Qual é o prazo?

Para o seu sistema, o prazo já começou. Segundo o calendário publicado pela Receita, os sistemas entraram em produção em 27/07/2026 e o primeiro CNPJ alfanumérico foi implementado em 31/07/2026.

Também segundo a Receita, a atribuição é progressiva e aleatória, e os dois formatos convivem. Uma inscrição nova ainda pode receber um número só com dígitos. Por isso não existe um dia em que “vira a chave”. O que existe é o dia em que um cliente seu digita um CNPJ com letras e o seu sistema recusa.

Quem atende empresas, emite nota ou recebe cadastro de fornecedor é o primeiro a ver o problema. A própria Receita avisa que sistema que não leia o novo formato pode ter dificuldade na emissão de notas e falhas na comunicação com clientes e fornecedores.

O que quebra quando o CNPJ vira texto com letras

Três coisas, nesta ordem de frequência:

1. Coluna numérica. Não aceita letra. No SQLite em modo STRICT, por exemplo, gravar O6J53RAJ000143 numa coluna inteira falha com cannot store TEXT value in INTEGER column. Outros bancos recusam de forma parecida.
2. Zeros à esquerda. Esse bug já existia, e a migração é a hora de limpá-lo. O CNPJ 00.123.456/0001-49 vira o número 123456000149 e perde dois dígitos. Num lote de 1.000 CNPJs numéricos gerados pelo site (semente 7), 94 começam com zero e perderiam pelo menos um caractere: cerca de 1 em cada 10.
3. Máscara e validação. Campo que só aceita dígitos e regex com \d recusam o formato novo antes de chegar ao banco.

Passo 1: ache onde o CNPJ aparece

Comece por um inventário, não pelo ALTER TABLE. Procure por nome de coluna e por tipo:

SELECT table_name, column_name, data_type
FROM information_schema.columns
WHERE (column_name ILIKE '%cnpj%' OR column_name ILIKE '%documento%')
  AND data_type IN ('bigint', 'integer', 'numeric', 'smallint');

ILIKE é do PostgreSQL; em outros bancos use LIKE com a função de maiúsculas do seu SGBD. Anote também chaves estrangeiras, índices, views, procedures, jobs de importação e arquivos de layout fixo. Colunas genéricas como documento ou cpf_cnpj entram na lista.

Passo 2: troque o tipo sem parar o sistema

Em tabela pequena, um ALTER COLUMN ... TYPE direto resolve (o guia da ferramenta traz esse comando). Em tabela grande, com o sistema no ar, use expandir e contrair:

-- 1. Expandir: coluna nova, ao lado da antiga.
ALTER TABLE empresa ADD COLUMN cnpj_texto CHAR(14);

-- 2. Preencher em lotes, completando os zeros à esquerda.
UPDATE empresa
SET cnpj_texto = lpad(cnpj::text, 14, '0')
WHERE cnpj_texto IS NULL AND id BETWEEN 1 AND 50000;

-- 3. Conferir: o que ficou fora do formato novo?
SELECT count(*) FROM empresa
WHERE cnpj_texto IS NULL OR cnpj_texto !~ '^[0-9A-Z]{12}[0-9]{2}$';

Repita o passo 2 para cada faixa de id. Quando a contagem do passo 3 der zero, crie o índice único (CREATE UNIQUE INDEX CONCURRENTLY no PostgreSQL), mude as leituras para a coluna nova e só então remova a antiga. Enquanto isso, a aplicação grava nas duas.

Esses três passos foram executados em SQLite, numa tabela de teste, com printf('%014d', cnpj) no lugar de lpad e glob no lugar de !~. O número 123456000149 virou 00123456000149, e a conferência apontou exatamente a linha com letra minúscula. Os comandos em SQL acima, escritos para PostgreSQL, não foram executados nesse banco: são a mesma lógica, simples o bastante para você conferir antes de rodar.

Passo 3: ajuste a aplicação e a API

O banco é a parte fácil. Em seguida, troque o tipo do campo no modelo (Long para String, int para string) e em todo DTO que o carrega.

Nas APIs, o risco é o contrato. Quem já consome o seu endpoint pode estar mandando e esperando número. Durante a transição, aceite os dois e devolva texto:

const normalizarCnpj = (v) => String(v ?? '').replace(/[.\/\-\s]/g, '').toUpperCase();

function cnpjParaTexto(valor) {
  // o legado manda número; o novo manda texto
  return typeof valor === 'number'
    ? String(valor).padStart(14, '0')
    : normalizarCnpj(valor);
}

cnpjParaTexto(123456000149);            // "00123456000149"
cnpjParaTexto('00.123.456/0001-49');    // "00123456000149"
cnpjParaTexto('o6.j53.raj/0001-43');    // "O6J53RAJ000143"

Documente a mudança no contrato (um campo string com o padrão ^[0-9A-Z]{12}[0-9]{2}$) e marque o formato numérico como obsoleto, em vez de quebrá-lo de uma vez.

Passo 4: máscara, relatórios e integrações

A máscara é a mesma de sempre, XX.XXX.XXX/XXXX-DV, com 14 caracteres, segundo a Receita. O que muda é o campo de tela, que precisa aceitar letras nas 12 primeiras posições e só dígitos nas 2 últimas.

Revise o que lê o CNPJ fora do código principal:

• planilhas e CSV, onde a coluna tem de ser texto;
• arquivos de layout fixo com campo numérico de 14 posições;
• relatórios e views que fazem CAST para número;
• regras que deduzem “é matriz” pelo 0001. A Receita avisa que o sufixo 0001 indica a matriz só na inscrição e que uma filial pode virar o estabelecimento principal depois.

Passo 5: teste com os dois formatos

Migração sem massa de teste é aposta. Monte uma lista com numéricos, alfanuméricos, filiais com letra na ordem e casos inválidos. O gerador de CNPJ faz o lote com semente, então o teste automatizado recebe sempre os mesmos números. Para conferir os números que entram, o validador mostra o cálculo do dígito.

Estes foram gerados pela biblioteca do site (sementes 2611 e 17) ou calculados por ela. São fictícios e servem só para teste de software:

O último caso é um dos exemplos do FAQ da Receita: raiz só com números e ordem da filial com letra. A mistura é permitida.

Checklist de fechamento

• Nenhuma coluna de CNPJ em tipo numérico.
• Valor gravado sem máscara, em maiúsculas, com 14 caracteres.
• Chaves, índices e views apontando para a coluna nova.
• API aceitando os dois formatos e devolvendo texto.
• Campo de tela aceitando letras nas 12 primeiras posições.
• Planilhas, relatórios e layouts fixos revisados.
• Teste automatizado com numéricos, alfanuméricos e inválidos.

Para gerar a massa de teste e ver o cálculo do dígito com o seu número, abra o gerador e guia do novo formato. Os números são fictícios e valem apenas para teste de software.