CPFHub.io

Consultar CPF com Java

Consulte CPF com Java usando java.net.http.HttpClient nativo. Sem dependências externas, Java 17+.

Usando Cursor, Lovable, v0 ou outra IA? Copie o prompt da Consulta Simples e cole no seu assistente.

Abrir no Cursor

Antes de começar

  1. Crie uma conta grátis em app.cpfhub.io: o plano Grátis tem 50 créditos e não pede cartão.
  2. Copie sua API Key em app.cpfhub.io/api-keys.
  3. Guarde a chave em uma variável de ambiente, nunca no código:
bash
export CPFHUB_API_KEY="sua_api_key"

Exemplo

Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ConsultaCpf {
    public static void main(String[] args) throws Exception {
        String cpf = "12345678909";

        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cpfhub.io/cpf/" + cpf))
            .header("x-api-key", System.getenv("CPFHUB_API_KEY"))
            .timeout(Duration.ofSeconds(10))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        switch (response.statusCode()) {
            // Leia o JSON com a biblioteca do seu projeto (Jackson, Gson etc.)
            case 200 -> System.out.println(response.body());
            case 404 -> System.out.println("CPF não encontrado (não consome crédito)");
            case 429 -> System.out.println("Limite por minuto atingido. Tente de novo em "
                + response.headers().firstValue("Retry-After").orElse("?") + " s");
            default -> throw new RuntimeException("Erro " + response.statusCode() + ": " + response.body());
        }
    }
}

Salve como ConsultaCpf.java e rode com java ConsultaCpf.java.

Resposta

CPF encontrado (200, consome 1 crédito):

JSON
{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "Fulano de Tal",
    "nameUpper": "FULANO DE TAL",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}

CPF não encontrado (404, não consome crédito):

JSON
{
  "success": false,
  "data": null,
  "error": { "message": "CPF não encontrado na base de dados" }
}

O CPF 12345678909 é fictício, usado só nos exemplos. gender pode vir null.

Erros

StatusO que significaO que fazer
404CPF não está na baseTrate como "não encontrado". Não consome crédito.
400 / 422CPF sem 11 dígitos ou com dígito verificador inválidoCorrija a entrada. Não consome crédito.
401API Key ausente ou inválidaConfira a variável CPFHUB_API_KEY.
403Créditos esgotados ou conta inativaVeja o saldo em GET /quota ou recarregue no dashboard.
429Limite de requisições por minutoEspere os segundos do header Retry-After e tente de novo.
5xxFalha temporáriaTente de novo após alguns segundos.

O campo error pode vir como texto ("error": "...") ou como objeto ("error": { "message": "..." }), conforme o status. Os exemplos acima tratam os dois formatos. Lista completa em Códigos de Erro.

Próximos passos