Gerador de CPF em lote

Para que serve um lote de CPFs

Um único CPF resolve o teste de um formulário. Muitos cenários, porém, precisam de volume: uma tabela de clientes com milhares de linhas, um teste de carga que cria cadastros em sequência, um relatório que só faz sentido com dados suficientes para paginar, agrupar e filtrar. Copiar números um a um do gerador de CPF não escala.

O gerador em lote produz de 1 a 10 mil CPFs de uma vez, todos com dígitos verificadores corretos e nenhum com dígitos todos iguais. Você escolhe:

• Quantidade: de 1 a 10.000. Valores fora desse intervalo são ajustados ao limite mais próximo.
• Estado: “Qualquer” sorteia o nono dígito; um estado específico fixa o nono dígito na região fiscal correspondente.
• Formato: com pontuação (000.000.000-00) ou só números.

O resultado aparece em uma caixa de texto, um CPF por linha, e pode ser copiado de uma vez ou baixado como arquivo CSV ou JSON.

Usos comuns:

• popular bancos de desenvolvimento e homologação com dados que passam nas mesmas validações da produção;
• montar fixtures para testes de integração que precisam de muitos registros distintos;
• testar importações de planilhas, com arquivos de tamanho realista;
• alimentar testes de carga e de desempenho de buscas por CPF.

CSV ou JSON: qual usar

Os dois arquivos contêm os mesmos números; o que muda é quem vai ler.

O CSV (cpfs.csv) tem uma coluna chamada cpf na primeira linha e um número por linha depois dela. É o formato certo para importar em banco de dados, abrir em planilha ou processar com ferramentas de linha de comando. Um cuidado: ao abrir em planilha, escolha “Só números” com a coluna como texto, ou o programa pode tratar o CPF como número e cortar zeros à esquerda.

O JSON (cpfs.json) é um array de strings, por exemplo ["52998224725", "04506643682"]. É o formato mais prático para fixtures de testes automatizados e para scripts, porque qualquer linguagem lê JSON sem configuração:

import { readFileSync } from 'node:fs';

const cpfs = JSON.parse(readFileSync('cpfs.json', 'utf8'));
console.log(cpfs.length); // quantidade gerada

Se o destino é um banco, prefira CSV. Se o destino é código, prefira JSON.

Importar no banco de dados

Para importação, gere o lote no modo “Só números”. Guardar o CPF como texto de 11 caracteres, sem pontuação, é a forma mais simples de manter buscas e índices consistentes. Os exemplos abaixo partem de uma tabela de teste com uma coluna cpf.

No PostgreSQL, o comando \copy do psql lê o arquivo da sua máquina e envia para o servidor. A opção HEADER pula a primeira linha, que contém o nome da coluna:

CREATE TABLE clientes_teste (
id  serial PRIMARY KEY,
cpf char(11) NOT NULL
);

\copy clientes_teste (cpf) FROM 'cpfs.csv' WITH (FORMAT csv, HEADER true)

O comando SQL COPY ... FROM 'arquivo', sem a barra, também funciona, mas lê o arquivo no sistema de arquivos do servidor e exige permissões específicas; para um arquivo baixado no seu computador, \copy é o caminho mais direto.

No MySQL, use LOAD DATA LOCAL INFILE. A cláusula IGNORE 1 LINES pula o cabeçalho:

CREATE TABLE clientes_teste (
  id  INT AUTO_INCREMENT PRIMARY KEY,
  cpf CHAR(11) NOT NULL
);

LOAD DATA LOCAL INFILE 'cpfs.csv'
  INTO TABLE clientes_teste
  FIELDS TERMINATED BY ','
  LINES TERMINATED BY '\n'
  IGNORE 1 LINES
  (cpf);

O LOCAL exige que a opção local_infile esteja habilitada no servidor e no cliente. Se a importação for recusada com erro de permissão, é essa a configuração a verificar.

Se a tabela tem UNIQUE na coluna cpf, lembre que cada número do lote é sorteado de forma independente: repetições são raras, mas possíveis. Remova duplicatas antes de importar ou use a cláusula de conflito do seu banco. Para levar a validação dos dígitos para dentro do banco, com CHECK ou função, veja o guia de validação de CPF em PostgreSQL e MySQL.

Gerar por estado

O nono dígito do CPF indica a região fiscal onde o número foi emitido. São dez regiões, numeradas de 0 a 9; algumas cobrem um único estado e outras agrupam vários:

Ao escolher um estado, todos os CPFs do lote recebem o nono dígito daquela região. Isso é útil quando o sistema testado usa essa informação, por exemplo para pré-selecionar um estado no cadastro ou para gerar relatórios regionais. Como a região agrupa estados, escolher ES ou RJ produz o mesmo resultado: o nono dígito será 7 nos dois casos. O guia sobre dígitos do CPF e regiões fiscais explica a origem dessa divisão e por que ela não indica onde a pessoa mora hoje.

Limites e desempenho

O lote é calculado inteiramente no navegador. Gerar um CPF exige duas somas de nove ou dez multiplicações, e até 10 mil números ficam prontos em menos de um segundo em um computador comum. O arquivo CSV ou JSON é montado na própria página e baixado sem passar por nenhum servidor.

Além do cálculo, a página precisa exibir o resultado na caixa de texto, e listas muito grandes tornam a rolagem e a cópia mais pesadas; por isso o lote vai até 10 mil. Para mais números, gere vários lotes ou leve a geração para o seu código.

A API pública oferece o mesmo recurso para scripts e pipelines:

GET https://www.cpf.dev.br/api/v1/cpf/gerar?quantidade=1000&uf=MG&formatado=false

Cada chamada devolve até 1000 CPFs no campo cpfs, e cada IP pode fazer até 60 requisições por minuto, sem chave. Para dezenas de milhares de registros em um seed, normalmente é mais simples copiar a função de geração da página de código da sua linguagem, como JavaScript ou Python, e gerar localmente. Lembre também que dados de teste devem ser fictícios do começo ao fim: o guia sobre CPF em massa de teste e LGPD mostra como montar uma base de homologação sem copiar dados reais.