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.
Antes de começar
- Crie uma conta grátis em app.cpfhub.io: o plano Grátis tem 50 créditos e não pede cartão.
- Copie sua API Key em app.cpfhub.io/api-keys.
- 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
| Status | O que significa | O que fazer |
|---|---|---|
404 | CPF não está na base | Trate como "não encontrado". Não consome crédito. |
400 / 422 | CPF sem 11 dígitos ou com dígito verificador inválido | Corrija a entrada. Não consome crédito. |
401 | API Key ausente ou inválida | Confira a variável CPFHUB_API_KEY. |
403 | Créditos esgotados ou conta inativa | Veja o saldo em GET /quota ou recarregue no dashboard. |
429 | Limite de requisições por minuto | Espere os segundos do header Retry-After e tente de novo. |
5xx | Falha temporária | Tente 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.