API - v1 - Dados BR

Documentacao da API

Gere e valide dados brasileiros sinteticos por HTTP. Tudo em JSON, chamavel de qualquer linguagem, sem SDK. Esta pagina mostra como autenticar e como fazer cada chamada, com exemplo pronto de curl e da resposta.

Pegar minha chave Ver planos e precos

Introducao

A API roda no edge da Cloudflare e responde sempre em JSON. Toda rota fica sob o prefixo /v1, a partir da URL base:

Base URL

https://api.tudoferramentas.com

Os dados sao 100% sinteticos: passam nos validadores (digito verificador, Luhn, formato), mas nao pertencem a ninguem. Servem para teste, staging e demonstracao.

Autenticacao

Toda chamada precisa da sua chave de API no cabecalho Authorization, com o esquema Bearer. As chaves comecam com tk_live_.

Cabecalho de autenticacao

Authorization: Bearer tk_live_sua_chave

Crie sua conta para receber a chave e 100 creditos gratis para testar. Guarde a chave como um segredo: quem a tem, gasta seus creditos.

!Sem chave valida, a resposta e 401 UNAUTHORIZED.

Formato da resposta

Sucesso vem sempre embrulhado em data. Erro vem embrulhado em error, com code estavel e message em portugues.

Sucesso

{
  "data": { "cpf": "529.982.247-25", "valido": true }
}

Erro

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Creditos insuficientes. Compre mais para continuar."
  }
}

Toda resposta bem-sucedida traz o cabecalho X-Credits-Remaining com o saldo de creditos que sobrou apos a chamada.

Creditos e custos

Cada chamada bem-sucedida desconta creditos do seu saldo. Geracao custa creditos inteiros; validacao custa a fracao de 1 credito a cada 10 chamadas.

Endpoint	Custo
`GET /v1/cpf`	1 credito
`GET /v1/cnpj`	1 credito
`GET /v1/cartao-credito`	2 creditos
`GET /v1/pessoas`	4 creditos
`POST /v1/cpf/validar`	1 credito / 10 chamadas
`POST /v1/cnpj/validar`	1 credito / 10 chamadas

Erros

O codigo HTTP e o campo error.code dizem o que aconteceu. Trate ao menos estes:

HTTP	code	Quando acontece
`400`	`BAD_REQUEST`	Parametro ou corpo JSON invalido (ex: uf que nao existe).
`401`	`UNAUTHORIZED`	Chave de API ausente, mal formada ou revogada.
`402`	`INSUFFICIENT_CREDITS`	Sua conta ficou sem creditos. Compre mais para continuar.
`404`	`NOT_FOUND`	Endpoint ou metodo que nao existe.
`429`	`RATE_LIMITED`	Requisicoes demais em pouco tempo. Espere alguns instantes.

Limites e CORS

Ha um limite de requisicoes por segundo por chave. Ao estourar, a resposta e 429 RATE_LIMITED; espere alguns instantes e tente de novo. Os endpoints publicos liberam CORS para qualquer origem, entao voce pode chamar a API direto do navegador.

Referencia

Endpoints

GET/v1/cpf1 credito

Gerar CPF

Retorna um CPF sintetico com digito verificador valido e o estado de origem embutido no numero.

Parametro	Tipo	Obrigatorio	Padrao	Descricao
`uf`	string	nao	aleatoria	Sigla do estado de origem (ex: SP, RJ, MG). Sem ela, o estado e sorteado.

Requisicao

curl "https://api.tudoferramentas.com/v1/cpf?uf=SP" \
  -H "Authorization: Bearer tk_live_sua_chave"

Resposta 200

{
  "data": {
    "cpf": "529.982.247-25",
    "estado_origem": "SP",
    "data_geracao": "2026-09-05T12:00:00.000Z",
    "valido": true
  }
}

GET/v1/cnpj1 credito

Gerar CNPJ

Retorna um CNPJ sintetico valido, de matriz ou filial, no formato numerico ou alfanumerico (mandatario desde jan/2026).

Parametro	Tipo	Obrigatorio	Padrao	Descricao
`matriz`	boolean	nao	true	true gera matriz (ordem 0001), false gera filial.
`formato`	string	nao	numerico	numerico ou alfanumerico. O alfanumerico segue o novo padrao da Receita.

Requisicao

curl "https://api.tudoferramentas.com/v1/cnpj?formato=alfanumerico&matriz=false" \
  -H "Authorization: Bearer tk_live_sua_chave"

Resposta 200

{
  "data": {
    "cnpj": "12.ABC.345/01DE-35",
    "tipo": "filial",
    "formato": "alfanumerico",
    "data_geracao": "2026-09-05T12:00:00.000Z",
    "valido": true
  }
}

GET/v1/pessoas4 creditos

Gerar pessoa completa

Retorna uma pessoa coerente: nome, CPF e RG, nascimento e idade, contatos e endereco com CEP do estado certo.

Requisicao

curl "https://api.tudoferramentas.com/v1/pessoas" \
  -H "Authorization: Bearer tk_live_sua_chave"

Resposta 200

{
  "data": {
    "nome": "Marina Alves Ribeiro",
    "cpf": "390.533.447-05",
    "rg": "34.567.890-1",
    "nascimento": "14/03/1991",
    "idade": 35,
    "sexo": "Feminino",
    "email": "marina.alves482@exemplo.com.br",
    "celular": "(11) 98765-4321",
    "telefone": "(11) 3456-7890",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "742",
      "bairro": "Centro",
      "cidade": "Campinas",
      "uf": "SP",
      "cep": "13010-111"
    },
    "profissao": "Arquiteta",
    "signo": "Peixes",
    "altura": "1.68 m",
    "peso": "62 kg",
    "cor": "Azul",
    "data_geracao": "2026-09-05T12:00:00.000Z"
  }
}

GET/v1/cartao-credito2 creditos

Gerar cartao de credito

Retorna um numero de cartao ficticio que passa no Luhn, com BIN real por bandeira. Serve para teste de checkout, nunca para transacao.

Parametro	Tipo	Obrigatorio	Padrao	Descricao
`bandeira`	string	nao	aleatoria	Visa, Mastercard, American Express, Discover, Diners Club, Elo ou Hipercard.

Requisicao

curl "https://api.tudoferramentas.com/v1/cartao-credito?bandeira=Visa" \
  -H "Authorization: Bearer tk_live_sua_chave"

Resposta 200

{
  "data": {
    "numero": "4539 5678 9012 3456",
    "numero_raw": "4539567890123456",
    "bandeira": "Visa",
    "data_geracao": "2026-09-05T12:00:00.000Z"
  }
}

POST/v1/cpf/validar1 credito a cada 10 chamadas

Validar CPF

Confere formato e digito verificador de um CPF. Aceita com ou sem pontuacao.

Parametro	Tipo	Obrigatorio	Padrao	Descricao
`cpf`	string	sim	-	No corpo JSON. O CPF a validar, ex: "529.982.247-25" ou "52998224725".

Requisicao

curl -X POST "https://api.tudoferramentas.com/v1/cpf/validar" \
  -H "Authorization: Bearer tk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"cpf":"529.982.247-25"}'

Resposta 200

{
  "data": {
    "cpf": "529.982.247-25",
    "valido": true
  }
}

POST/v1/cnpj/validar1 credito a cada 10 chamadas

Validar CNPJ

Confere formato e digito verificador de um CNPJ, inclusive o novo formato alfanumerico.

Parametro	Tipo	Obrigatorio	Padrao	Descricao
`cnpj`	string	sim	-	No corpo JSON. O CNPJ a validar, numerico ou alfanumerico.

Requisicao

curl -X POST "https://api.tudoferramentas.com/v1/cnpj/validar" \
  -H "Authorization: Bearer tk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"cnpj":"11.222.333/0001-81"}'

Resposta 200

{
  "data": {
    "cnpj": "11.222.333/0001-81",
    "valido": true
  }
}

Pronto para a primeira chamada?

Crie a conta, copie a chave e cole o curl acima. 100 creditos gratis para comecar.

Criar conta gratis