v1.0REST · JSON · Gratuita · Sem autenticação

API de CPF

API pública e gratuita para gerar e validar CPFs fictícios. Ideal para testes automatizados, seeds de banco de dados e integração com pipelines de CI/CD. Sem chave de API, sem cadastro.

GET /api/cpfGET /api/cpf/validate

URL Base

https://geradordecpf.com.br

Todas as requisições usam HTTPS. CORS habilitado para qualquer origem.

GET/api/cpf

Gera um ou mais CPFs fictícios e matematicamente válidos. Suporta filtragem por estado (UF) e retorno em JSON ou texto plano.

Parâmetros de query

ParâmetroTipoPadrãoDescrição
countinteger1Quantidade de CPFs (1–100)
ufstringrandomSigla do estado (SP, RJ, MG…) para fixar o 9º dígito regional. Omita para aleatório.
maskedbooleantruetrue retorna formato 000.000.000-00, false retorna apenas os 11 dígitos.
formatstringjsonjson (padrão) ou text (CPFs separados por quebra de linha, útil para scripts shell).

Exemplos de uso

cURL — 1 CPF simples

curl "https://geradordecpf.com.br/api/cpf"

cURL — 5 CPFs de SP sem máscara

curl "https://geradordecpf.com.br/api/cpf?count=5&uf=SP&masked=false"

JavaScript (fetch)

const res = await fetch("https://geradordecpf.com.br/api/cpf?count=3&uf=RJ");
const { cpfs } = await res.json();
console.log(cpfs); // ["123.456.789-09", ...]

Python (httpx)

import httpx

r = httpx.get("https://geradordecpf.com.br/api/cpf", params={"count": 10, "masked": "false"})
data = r.json()
print(data["cpfs"])  # ['12345678909', ...]

Shell — gerar lista e salvar em arquivo

curl -s "https://geradordecpf.com.br/api/cpf?count=50&format=text&masked=false" > cpfs.txt

Respostas

200 OK — count=1

{"cpf": "123.456.789-09", "masked": true}

200 OK — count>1

{
  "cpfs": ["123.456.789-09", "987.654.321-00"],
  "count": 2,
  "masked": true
}

400 Bad Request — parâmetro inválido

{
  "error": "Parâmetro inválido",
  "message": "'count' deve ser um inteiro entre 1 e 100.",
  "docs": "https://geradordecpf.com.br/api-docs"
}
Playground

Requisição

GET/api/cpf
GET/api/cpf/validate

Valida um CPF e retorna informações detalhadas: dígitos verificadores, dígito regional e estados possíveis de origem. Aceita CPF com ou sem formatação.

Parâmetros de query

ParâmetroTipoObrigatórioDescrição
cpfstringsimCPF a validar. Aceita com ou sem máscara (ex.: 123.456.789-09 ou 12345678909).

Exemplos de uso

cURL — CPF formatado

curl "https://geradordecpf.com.br/api/cpf/validate?cpf=123.456.789-09"

JavaScript (fetch)

const cpf = "12345678909";
const res = await fetch(`https://geradordecpf.com.br/api/cpf/validate?cpf=${cpf}`);
const { valid, possibleStates } = await res.json();

if (!valid) throw new Error("CPF inválido");
console.log("Estados possíveis:", possibleStates); // ["PR", "SC"]

Respostas

200 OK — CPF válido

{
  "valid": true,
  "formatted": "123.456.789-09",
  "digits": "12345678909",
  "regionalDigit": 9,
  "possibleStates": ["PR", "SC"]
}

200 OK — CPF inválido

{
  "valid": false,
  "formatted": "123.456.789-00",
  "digits": "12345678900",
  "regionalDigit": 9,
  "possibleStates": ["PR", "SC"],
  "reason": "Dígitos verificadores incorretos."
}
Playground

Requisição

GET/api/cpf/validate?cpf=

Limites e Termos de Uso

  • Limite por requisição: máximo de 100 CPFs por chamada ao endpoint de geração.
  • Rate limit: uso justo esperado. Para volumes muito altos, considere hospedar sua própria instância — o projeto é open source.
  • CORS: habilitado para qualquer origem (Access-Control-Allow-Origin: *).
  • Autenticação: não necessária. A API é pública e gratuita.
  • Uso permitido: exclusivamente para testes de software, desenvolvimento e fins educacionais. Veja o Aviso Legal.