API REST de CPF e CNPJ

Endpoints HTTP gratuitos para validar, gerar e formatar CPFs e CNPJs — incluindo o formato alfanumérico —, sem necessidade de chave de acesso. Respostas em JSON, CORS liberado para qualquer origem.

Endpoints — CPF

As rotas antigas (/api/v1/validar/{cpf}, /api/v1/gerar e /api/v1/formatar) continuam funcionando e redirecionam permanentemente (308) para os caminhos abaixo.

Método	Rota	Parâmetros
`GET`	`/api/v1/cpf/validar/{cpf}`	{cpf} na URL (com ou sem máscara)
`GET`	`/api/v1/cpf/gerar`	quantidade (1–1000, padrão 1), uf (opcional), formatado (true/false)
`GET`	`/api/v1/cpf/formatar`	cpf (obrigatório, na query string)
`GET`	`/api/v1/health`	— nenhum

Exemplo de resposta — /api/v1/cpf/validar/{cpf}

{
  "valido": true,
  "cpf": "52998224725",
  "formatado": "529.982.247-25",
  "uf": ["ES", "RJ"]
}

Exemplo de resposta — /api/v1/cpf/gerar

{
  "cpfs": ["529.982.248-06"]
}

Exemplo de resposta — /api/v1/cpf/formatar

{
  "formatado": "529.982.247-25",
  "limpo": "52998224725",
  "valido": true
}

Exemplo de resposta — /api/v1/health

{
  "ok": true,
  "version": 1
}

Endpoints — CNPJ

Mesmo padrão dos endpoints de CPF, com suporte nativo ao CNPJ alfanumérico (12 posições em [A-Z0-9] + 2 dígitos verificadores numéricos).

Método	Rota	Parâmetros
`GET`	`/api/v1/cnpj/validar/{cnpj}`	{cnpj} na URL, sem máscara (ex.: 12ABC34501DE35) ou com máscara desde que a barra vá como %2F (ex.: 12.ABC.345%2F01DE-35); aceita letras do formato alfanumérico
`GET`	`/api/v1/cnpj/gerar`	quantidade (1–1000, padrão 1), formato (numerico ou alfanumerico, padrão numerico), raiz (opcional, 8 caracteres), ordem (opcional, 4 caracteres), formatado (true/false)
`GET`	`/api/v1/cnpj/formatar`	cnpj (obrigatório, na query string)

Exemplo de resposta — /api/v1/cnpj/validar/{cnpj}

{
  "valido": true,
  "cnpj": "12ABC34501DE35",
  "formatado": "12.ABC.345/01DE-35",
  "formato": "alfanumerico",
  "raiz": "12ABC345",
  "ordem": "01DE",
  "matriz": false
}

Exemplo de resposta — /api/v1/cnpj/gerar

{
  "cnpjs": ["12.ABC.345/01DE-35"]
}

Exemplo de resposta — /api/v1/cnpj/formatar

{
  "formatado": "12.ABC.345/01DE-35",
  "limpo": "12ABC34501DE35",
  "valido": true,
  "formato": "alfanumerico"
}

Na rota /api/v1/cnpj/validar/{cnpj}, o CNPJ pode ir sem máscara (12ABC34501DE35) ou com máscara, desde que a barra seja enviada como %2F (12.ABC.345%2F01DE-35) — o endpoint decodifica o parâmetro antes de validar. Uma barra literal não escapada (/0001-35) é interpretada como mais um segmento de path e resulta em 404.

Limites

60 requisições por minuto por IP, aplicado a todos os endpoints em /api/v1 (requisições OPTIONS não contam no limite).
Lote de geração limitado a 1000 CPFs ou CNPJs por requisição (quantidade entre 1 e 1000).
Nenhuma chave de API é necessária.
Ao exceder o limite, a resposta tem status 429 e cabeçalho Retry-After com o número de segundos até a próxima tentativa.
validar e formatar respondem com Cache-Control: public, max-age=86400; gerar responde com no-store.

CORS

Todos os endpoints respondem com Access-Control-Allow-Origin: *, permitindo chamadas diretamente do navegador a partir de qualquer origem. Os métodos aceitos são GET e OPTIONS.

Erros

Erros retornam um corpo JSON no formato:

Formato de erro

{
  "erro": {
    "codigo": "entrada_invalida",
    "mensagem": "..."
  }
}

Código	Significado
`entrada_invalida`	O valor enviado não tem o formato esperado (ex.: CPF com tamanho errado, CNPJ com menos de 14 caracteres).
`quantidade_invalida`	`quantidade` ausente, não inteira ou fora do intervalo 1–1000.
`uf_invalida`	A sigla informada em `uf` não corresponde a uma UF válida.
`formato_invalido`	`formato` (endpoints de CNPJ) diferente de `numerico` ou `alfanumerico`.
`raiz_invalida`	`raiz` (endpoint `/api/v1/cnpj/gerar`) não tem 8 caracteres válidos para o formato escolhido.
`ordem_invalida`	`ordem` (endpoint `/api/v1/cnpj/gerar`) não tem 4 caracteres válidos para o formato escolhido.
`parametro_ausente`	Um parâmetro obrigatório não foi informado (ex.: `cpf` em /cpf/formatar, `cnpj` em /cnpj/formatar).
`limite_excedido`	O limite de 60 requisições por minuto por IP foi excedido.
`nao_encontrado`	A rota chamada não existe em /api/v1.

Exemplos

curl — CPF

curl "https://www.cpf.dev.br/api/v1/cpf/validar/529.982.247-25"

JavaScript (fetch) — CPF

const resposta = await fetch('https://www.cpf.dev.br/api/v1/cpf/validar/529.982.247-25');
const dados = await resposta.json();
console.log(dados.valido, dados.uf);

Python (requests) — CPF

import requests

resposta = requests.get("https://www.cpf.dev.br/api/v1/cpf/validar/529.982.247-25")
dados = resposta.json()
print(dados["valido"], dados["uf"])

PHP (file_get_contents) — CPF

<?php
$resposta = file_get_contents('https://www.cpf.dev.br/api/v1/cpf/validar/529.982.247-25');
$dados = json_decode($resposta, true);
echo $dados['valido'] ? 'válido' : 'inválido';

curl — CNPJ alfanumérico (com máscara, barra como %2F)

curl "https://www.cpf.dev.br/api/v1/cnpj/validar/12.ABC.345%2F01DE-35"

curl — CNPJ alfanumérico (sem máscara)

curl "https://www.cpf.dev.br/api/v1/cnpj/validar/12ABC34501DE35"

JavaScript (fetch) — CNPJ alfanumérico

const resposta = await fetch('https://www.cpf.dev.br/api/v1/cnpj/validar/12ABC34501DE35');
const dados = await resposta.json();
console.log(dados.valido, dados.formato);