API de consulta de CPF.
Integre ao seu sistema.

Sua próxima integração começa com um prompt.#

Escolha o ambiente, copie as instruções e entregue ao seu agente. O prompt inclui o contrato da API, estados da interface, autenticação, créditos e testes.

Implemente esta integração no meu projeto Lovable. Detecte o backend disponível: use uma função de servidor ou Edge Function conforme a arquitetura existente. Solicite CPF_DIRETO_KEY pelo formulário de secrets. O navegador chama somente a função protegida da aplicação. Não coloque a chave na conversa.

Integre CPF Direto em uma aplicação existente, respeitando a arquitetura e os padrões do projeto.
Contrato: https://cpfdireto.com/api/openapi.json
Guia: https://cpfdireto.com/api-guide.md
Base: https://cpfdireto.com (as rotas já incluem /api/v1).

1. Implemente a chamada no backend. Guarde CPF_DIRETO_KEY como segredo no servidor; solicite seu preenchimento pelo gerenciador de segredos, nunca pelo chat. Não exponha a chave em frontend, bundle, logs, URLs ou localStorage.
2. Proteja a rota da sua aplicação com autenticação, autorização por usuário e limite de uso. Não crie um proxy público para uma chave paga. Preserve o controle de origem/CSRF quando usar cookies.
3. Envie Authorization: Bearer <CPF_DIRETO_KEY> e Content-Type: application/json. POST /api/v1/consultas recebe {"cpf":"12345678909"}. CPF é string, nunca número. Preserve zeros iniciais; valide 11 dígitos e verificadores antes de enviar.
4. HTTP 200 pode ser {success:true,data:{name,cpf,birthday,gender},meta:{remainingCredits,consultedAt}} OU {success:false,data:null,meta:{remainingCredits,consultedAt}}. Não confunda ausência de registro com erro HTTP. birthday é YYYY-MM-DD; gender é M, F ou null. consultedAt é ISO 8601 UTC de processamento, não de atualização da fonte.
5. POST /api/v1/lotes recebe {cpfs:[strings]}, de 1 a 100 itens. Retorna {results:[{success,data}],meta}, em ordem e incluindo duplicatas. Inválidos e ausentes têm success:false/data:null. Cada ocorrência encontrada custa 1 crédito; duplicatas custam novamente. HTTP 402 cancela o débito de todo o lote.
6. GET /api/v1/saldo retorna {remainingCredits,includedCredits,includedUsed,extraCredits,renewsAt}. Use renewsAt para renovação; saldo não reserva créditos. GET /api/v1/historico retorna {rows,total}; filtros limit (1–500, padrão 500), offset (>=0), q (até 120 caracteres, busca mascarada), status, type, from e to (datas inclusivas em Brasília). /api/v1/historico.csv usa os mesmos filtros e paginação e retorna CSV UTF-8 com BOM e ponto e vírgula; erros são JSON.
7. Erros JSON: {error:{code,message}}. Trate status HTTP + error.code: 400 invalid_cpf/request_error, 401 unauthorized/invalid_api_key/request_error, 402 credits_exhausted, 403 email_unverified/billing_hold/request_error, 404 request_error, 413 request_error, 415 request_error, 429 rate_limited, 500 server_error e 503 catalog_unavailable/catalog_busy/real_data_disabled. A mensagem pode variar. Em 429, respeite Retry-After em segundos. Registre X-Request-Id sem documentos ou chaves.
8. Limite padrão: 120 requisições/minuto por conta, compartilhadas entre chaves e consultas do painel; observe X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (Unix em segundos) quando presentes. Um lote conta como uma requisição. Saldo/histórico não gastam créditos, mas contam nesse limite.
9. Configure timeout e cancelamento, impeça duplo envio, mostre carregamento, encontrado, não encontrado, entrada inválida, falta de saldo e indisponibilidade. Não repita POST automaticamente após timeout, erro 500 ou falha de rede: pode ter sido cobrado. Não há garantia de idempotência nem suporte documentado a Idempotency-Key nas consultas. Limite as tentativas; não faça polling de consultas.
10. Renderize nomes como texto, sem HTML; evite cache público, analytics e logs com dados pessoais. Não apresente a consulta como prova de identidade, score ou situação fiscal. Não invente SDK, MCP, webhook ou endpoint de sandbox.
11. Escreva testes de contrato com respostas locais: encontrado com gender:null, não encontrado 200, erros 400/401/402/403/429/503, timeout incerto e lote misto. Não use consultas pagas nos testes automáticos. Documente onde preencher o segredo e como executar o projeto.

Auth0 cuida do login da sua aplicação. Seu backend valida o usuário e utiliza a chave do CPF Direto para fazer a consulta.

Autenticação#

1. Crie e confirme sua conta.

   Comece no plano Grátis e confirme o e-mail para liberar consultas.

2. Gere sua chave no painel.

   Abra API → Chaves de API. Guarde a chave em um segredo do servidor; você pode revogá-la ou substituí-la pelo painel.

3. Envie o cabeçalho em cada chamada.

   Todas as rotas desta referência exigem a chave. POST também exige Content-Type: application/json.

Authorization: Bearer SUA_CHAVE
Content-Type: application/json

Faça a primeira requisição#

Defina CPF_DIRETO_KEY no ambiente do servidor. Envie o CPF no corpo JSON; ele deve ser uma string para preservar zeros iniciais.

curl --include --max-time 15 --request POST \
  https://cpfdireto.com/api/v1/consultas \
  --header "Authorization: Bearer $CPF_DIRETO_KEY" \
  --header "Content-Type: application/json" \
  --data '{"cpf": "12345678909"}'

Os exemplos mostram a chamada HTTP completa. No seu fluxo, trate os erros HTTP e depois verifique success. Use os dados exibidos apenas para entender o formato; eles não garantem um resultado no catálogo.

Consultar um CPF#

Informe o CPF como string, com ou sem pontuação, até 32 caracteres. Os 11 dígitos e os verificadores são validados. Preserve zeros iniciais. Um registro encontrado consome 1 crédito; um CPF válido sem registro retorna HTTP 200, success: false e data: null, sem cobrança.

{
  "cpf": "12345678909"
}

{
  "success": true,
  "data": {
    "name": "Pessoa de exemplo",
    "cpf": "12345678909",
    "birthday": "1990-06-15",
    "gender": null
  },
  "meta": {
    "remainingCredits": 19,
    "consultedAt": "2026-10-14T15:30:00.000Z"
  }
}

Erros possíveis: 400, 401, 402, 403, 404, 413, 415, 429, 500 e 503. Ver códigos e tratamento.

Consultar em lote#

Envie cpfs como uma lista de 1 a 100 strings, com até 32 caracteres cada. A resposta é síncrona e mantém a ordem, incluindo repetições. Itens inválidos e não encontrados retornam success: false e data: null. Valide os dígitos antes de enviar para distingui-los. Cada ocorrência encontrada custa 1 crédito; repetições também são cobradas. Com saldo insuficiente, todo o envio retorna 402 sem débito parcial.

{
  "cpfs": [
    "12345678909",
    "52998224725"
  ]
}

{
  "results": [
    {
      "success": true,
      "data": {
        "name": "Pessoa de exemplo",
        "cpf": "12345678909",
        "birthday": "1990-06-15",
        "gender": null
      }
    },
    {
      "success": false,
      "data": null
    }
  ],
  "meta": {
    "remainingCredits": 19,
    "consultedAt": "2026-10-14T15:30:00.000Z"
  }
}

Erros possíveis: 400, 401, 402, 403, 404, 413, 415, 429, 500 e 503. Ver códigos e tratamento.

Consultar saldo#

Retorna o saldo atual, a franquia do plano, o consumo da franquia, os créditos adicionais e a próxima renovação. Não consome créditos, mas conta no limite de requisições. O saldo é informativo e não reserva créditos para outra requisição.

{
  "remainingCredits": 19,
  "includedCredits": 20,
  "includedUsed": 1,
  "extraCredits": 0,
  "renewsAt": "2026-11-01T03:00:00.000Z"
}

remainingCredits

Total de créditos disponíveis agora.

includedCredits / includedUsed

Franquia mensal e quantidade já utilizada dessa franquia.

extraCredits

Créditos adicionais ainda disponíveis.

renewsAt

Próxima renovação em ISO 8601 UTC. O plano pago depende da confirmação do pagamento do período.

Erros possíveis: 401, 403, 404, 429 e 500. Ver códigos e tratamento.

Consultar histórico#

Retorna somente as operações da sua conta, da mais recente para a mais antiga, com documentos mascarados. rows contém a página; total é o número de itens que correspondem aos filtros, antes da paginação. Sem resultados: rows: [] e total: 0. Não consome créditos; conta no limite de requisições.

Filtros e paginação

Todos são opcionais. Codifique os valores na URL. A paginação usa offset; novas consultas podem deslocar páginas durante a leitura.

https://cpfdireto.com/api/v1/historico?limit=20&offset=0&from=2026-10-01&to=2026-10-31&status=Encontrado

{
  "rows": [
    {
      "id": "10946738-6d63-40a0-bd01-5ee2a40de9cd",
      "document": "***.456.789-**",
      "status": "Encontrado",
      "type": "Individual",
      "date": "2026-10-14T15:30:00.000Z",
      "chargedCredits": 1
    }
  ],
  "total": 1
}

chargedCredits é 0 ou 1; date é ISO 8601 UTC. id identifica o item do histórico. Nome e dados cadastrais completos não são retornados aqui.

Erros possíveis: 400, 401, 403, 404, 429 e 500. Ver códigos e tratamento.

Exportar histórico#

Mesmos filtros e paginação do histórico JSON, inclusive o máximo de 500 linhas por chamada. Retorna text/csv; charset=utf-8 com BOM, separador ponto e vírgula e campos entre aspas. Use offset para exportar mais páginas. Erros continuam sendo JSON. Não consome créditos; conta no limite de requisições.

"Documento";"Resultado";"Tipo";"Data";"Créditos consumidos"
"***.456.789-**";"Encontrado";"Individual";"2026-10-14T15:30:00.000Z";"1"

Erros possíveis: 400, 401, 403, 404, 429 e 500. Ver códigos e tratamento.

Entenda os campos da consulta#

As consultas retornam somente o resultado e meta. Não incluem dados da conta, preços ou histórico. O alias POST /api/v1/consulta permanece compatível; use /api/v1/consultas em integrações novas.

Status HTTP e códigos de erro#

Leia o status HTTP primeiro. Em erros, a resposta contém error.code e error.message, sem data ou meta. Use o código para decidir o fluxo; o texto da mensagem pode variar.

{
  "error": {
    "code": "invalid_cpf",
    "message": "Confira os 11 dígitos e digite um CPF válido."
  }
}

Corrija o CPF antes de reenviar.

Guarde o cabeçalho X-Request-Id ao reportar uma falha. O identificador fica no cabeçalho, não no JSON. Não envie sua chave ou documentos completos ao registrar um chamado.

Limites, créditos e novas tentativas#

Requisições e créditos são contagens diferentes

O limite padrão é de 120 requisições por minuto por conta, compartilhado entre chaves e chamadas do painel às rotas v1. Um lote conta como uma requisição, mas cada CPF encontrado consome um crédito. Saldo e histórico entram no limite de requisições sem consumir créditos.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1791991860
X-Request-Id: 10946738-6d63-40a0-bd01-5ee2a40de9cd

Os cabeçalhos de quota são enviados quando disponíveis; X-RateLimit-Reset usa segundos Unix. Em HTTP 429, leia Retry-After em segundos. Não dependa de receber os demais cabeçalhos no erro.

Renovação e saldo

O plano Grátis renova a franquia no início do mês em Brasília. O plano pago acompanha o período efetivamente pago da assinatura. A franquia não acumula; créditos adicionais permanecem até o consumo. Use renewsAt retornado pelo saldo. Consultar planos.

Reenvio com controle

• 400, 401, 402, 403, 404, 413 e 415: corrija a causa antes de reenviar.
• 429: aguarde Retry-After, limite tentativas e reduza concorrência.
• 503: use espera progressiva com variação aleatória e limite tentativas; real_data_disabled depende da habilitação do serviço.
• Timeout, erro 500 ou conexão interrompida: o processamento pode ter ocorrido. Não repita consultas automaticamente.

O corpo JSON aceita até 128.000 bytes. Todos os exemplos de timeout nesta página são escolhas do cliente; não representam uma garantia de tempo de resposta.

Playground#

Explore respostas sem credenciais ou envie uma requisição real com sua chave. A URL da requisição real usa este mesmo servidor.

{
  "success": true,
  "data": {
    "name": "Pessoa de exemplo",
    "cpf": "12345678909",
    "birthday": "1990-06-15",
    "gender": null
  },
  "meta": {
    "remainingCredits": 19,
    "consultedAt": "2026-10-14T15:30:00.000Z"
  }
}

Perguntas frequentes#