Primeira consulta de CPF pela API: passo a passo

A primeira integração deve responder a três perguntas: a chave funciona, o servidor entende o pedido e sua aplicação sabe interpretar o resultado? Comece por uma consulta isolada antes de conectar um formulário inteiro ou importar uma lista.

Neste roteiro, a chamada parte do seu backend. A chave da conta não deve aparecer no JavaScript entregue ao navegador. Você também precisa de um CPF que tenha autorização para consultar; o comando usa uma variável para evitar números pessoais no tutorial.

Prepare a conta e as variáveis

Crie sua conta, confirme o e-mail quando solicitado e obtenha a chave na área de API. No ambiente do servidor, configure CPF_DIRETO_KEY e CPF_AUTORIZADO. Mantenha essas variáveis fora do repositório e de capturas compartilhadas.

Confira o saldo no painel antes do teste. Consultas encontradas consomem um crédito; o mesmo saldo atende às chamadas da API e às consultas pelo painel.

Envie a consulta por POST

O endpoint é /api/v1/consultas. A autenticação usa Authorization: Bearer, o corpo é JSON e o CPF deve ser enviado como texto.

curl --fail-with-body --max-time 15 \
  'https://cpfdireto.com/api/v1/consultas' \
  -H "Authorization: Bearer $CPF_DIRETO_KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"cpf\":\"$CPF_AUTORIZADO\"}"

O exemplo pressupõe uma variável contendo apenas os 11 dígitos previamente validados. Em uma aplicação, use o serializador JSON da linguagem para montar o corpo; não concatene entradas arbitrárias em comandos de shell.

Leia o resultado antes de preencher o cadastro

Uma resposta processada contém success, data e meta. Quando há resultado, os dados estão em data.name, data.cpf, data.birthday e data.gender. O nascimento usa o formato AAAA-MM-DD; gênero pode ser M, F ou null.

Quando success é falso e data é nulo, não houve cadastro encontrado. Esse resultado pode vir com HTTP 200: a requisição foi processada normalmente. Não transforme toda resposta 200 em “pessoa encontrada”.

Em meta, remainingCredits informa o saldo após o processamento e consultedAt registra o horário da consulta. Nenhum desses campos representa a data de atualização do cadastro.

Faça a integração lidar com falhas

• Corrija entradas recusadas com 400 antes de enviar novamente.
• Revise credenciais em 401 e o saldo em 402.
• Em 429, respeite o tempo de espera de Retry-After.
• Para timeout, não conclua que nada foi processado no servidor.

Depois de testar os resultados de CPF encontrado e não encontrado, conecte a consulta ao seu produto. A referência da API reúne o contrato completo; a página de planos explica os créditos para o volume da sua operação.