SDK Java

SDK oficial para Java 11+ com suporte a Maven e Gradle, cliente HTTP não-bloqueante e tipos imutáveis.

Instalação

Maven

XML

<dependency>
  <groupId>io.cpfhub</groupId>
  <artifactId>cpfhub-java</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle

groovy

implementation 'io.cpfhub:cpfhub-java:1.0.0'

Requerimentos: Java 11+

Inicialização

Java

import io.cpfhub.CPFHub;
import io.cpfhub.CPFHubConfig;

CPFHub client = new CPFHub(CPFHubConfig.builder()
    .apiKey(System.getenv("CPFHUB_API_KEY"))
    // .timeout(Duration.ofSeconds(10)) // opcional
    .build());

Parâmetros do builder

Método	Tipo	Padrão	Descrição
`apiKey(String)`	`String`	-	Sua API Key (obrigatório)
`timeout(Duration)`	`Duration`	`PT10S`	Timeout da requisição
`baseUrl(String)`	`String`	`https://api.cpfhub.io`	URL base da API

Métodos

`client.lookup(String cpf)`

Consulta um CPF e retorna os dados de identidade.

Java

CPFHubResult result = client.lookup("12345678909");

System.out.println(result.getData().getName());   // "João da Silva"
System.out.println(result.getData().getGender()); // "M"

Retorno: CPFHubResult

Java

public class CPFHubResult {
    boolean success;
    CPFData data;
}

public class CPFData {
    String cpf;
    String name;
    String nameUpper;
    String gender;     // "M" | "F"
    String birthDate;  // "DD/MM/AAAA"
    int    day;
    int    month;
    int    year;
}

`client.lookupAsync(String cpf)`

Versão assíncrona usando CompletableFuture:

Java

CompletableFuture<CPFHubResult> future = client.lookupAsync("12345678909");
future.thenAccept(result -> System.out.println(result.getData().getName()));

Tratamento de erros

Java

import io.cpfhub.CPFHub;
import io.cpfhub.CPFHubException;

try {
    CPFHubResult result = client.lookup("12345678909");
} catch (CPFHubException e) {
    System.out.println(e.getCode());       // "CPF_NOT_FOUND"
    System.out.println(e.getMessage());    // "CPF not found in our database"
    System.out.println(e.getStatusCode()); // 404
}

Códigos de erro

`e.getCode()`	`e.getStatusCode()`	Descrição
`CPF_NOT_FOUND`	`404`	CPF não encontrado (sem consumo de crédito)
`INVALID_CPF_FORMAT`	`400`	Formato inválido
`INVALID_CPF_DIGITS`	`422`	Dígitos verificadores inválidos
`MISSING_API_KEY`	`401`	API Key ausente
`INVALID_API_KEY`	`401`	API Key inválida
`RATE_LIMIT_EXCEEDED`	`429`	Limite de taxa excedido
`INSUFFICIENT_CREDITS`	`403`	Sem créditos disponíveis

Exemplos de integração

Spring Boot - REST Controller

Java

@RestController
@RequestMapping("/cpf")
public class CPFController {

    private final CPFHub cpfhub = new CPFHub(CPFHubConfig.builder()
        .apiKey(System.getenv("CPFHUB_API_KEY"))
        .build());

    @GetMapping("/{cpf}")
    public ResponseEntity<?> consultar(@PathVariable String cpf) {
        try {
            CPFHubResult result = cpfhub.lookup(cpf);
            return ResponseEntity.ok(result.getData());
        } catch (CPFHubException e) {
            return ResponseEntity
                .status(e.getStatusCode())
                .body(Map.of("error", e.getCode()));
        }
    }
}

Spring Bean com injeção de dependência

Java

@Configuration
public class CPFHubConfig {

    @Bean
    public CPFHub cpfHub(@Value("${cpfhub.api-key}") String apiKey) {
        return new CPFHub(io.cpfhub.CPFHubConfig.builder()
            .apiKey(apiKey)
            .build());
    }
}

Repositório e suporte

github.com/cpfhub/cpfhub-java - código-fonte, issues e contribuições
Maven Central: io.cpfhub:cpfhub-java - versões e changelog

Atualizado em 12 de maio de 2026