DEV Community: CPFHub

Campo de CPF em React sem dor: máscara, validação em tempo real e acessibilidade

CPFHub — Tue, 13 Oct 2026 04:37:02 +0000

Transparência: sou fundador da CPFHub, citada no final. O componente funciona sem nenhuma API.

O campo de CPF parece trivial até você receber os primeiros tickets: "não consigo colar meu CPF", "o cursor pula para o final", "o teclado do celular abre com letras". Vamos construir um componente React que resolve tudo isso sem biblioteca de máscara.

1. Guarde dígitos, mostre máscara

O estado deve conter apenas dígitos. A máscara é derivada na renderização. Isso elimina a maior parte dos bugs.

const soDigitos = (s) => s.replace(/\D/g, "").slice(0, 11);

function mascararCpf(d) {
  return d
    .replace(/^(\d{3})(\d)/, "$1.$2")
    .replace(/^(\d{3})\.(\d{3})(\d)/, "$1.$2.$3")
    .replace(/\.(\d{3})(\d)/, ".$1-$2");
}

Teste rápido: mascararCpf("52998224725") → "529.982.247-25", e mascararCpf("5299") → "529.9". A máscara progressiva funciona enquanto o usuário digita.

2. Validação dos dígitos

export function cpfValido(d) {
  if (!/^\d{11}$/.test(d) || /^(\d)\1{10}$/.test(d)) return false;
  for (let t = 9; t < 11; t++) {
    let soma = 0;
    for (let i = 0; i < t; i++) soma += Number(d[i]) * (t + 1 - i);
    if (Number(d[t]) !== ((soma * 10) % 11) % 10) return false;
  }
  return true;
}

3. O componente

import { useId, useState } from "react";

export function CampoCpf({ onValido }) {
  const id = useId();
  const [digitos, setDigitos] = useState("");
  const [tocado, setTocado] = useState(false);

  const completo = digitos.length === 11;
  const valido = completo && cpfValido(digitos);
  const erro = tocado && digitos.length > 0 && (!completo || !valido);

  return (
    <div>
      <label htmlFor={id}>CPF</label>
      <input
        id={id}
        name="cpf"
        inputMode="numeric"
        autoComplete="off"
        placeholder="000.000.000-00"
        value={mascararCpf(digitos)}
        onChange={(e) => {
          const d = soDigitos(e.target.value);
          setDigitos(d);
          if (d.length === 11 && cpfValido(d)) onValido?.(d);
        }}
        onBlur={() => setTocado(true)}
        aria-invalid={erro}
        aria-describedby={erro ? `${id}-erro` : undefined}
      />
      {erro && (
        <p id={`${id}-erro`} role="alert">
          {completo ? "CPF inválido. Confira os números." : "O CPF tem 11 dígitos."}
        </p>
      )}
    </div>
  );
}

Decisões que importam:

inputMode="numeric" abre o teclado numérico no celular, mas, ao contrário de type="number", mantém o campo como texto (não perde zero à esquerda nem aceita e).
Erro só depois do blur. Mostrar "CPF inválido" enquanto a pessoa ainda digita o terceiro número é irritante.
Colar funciona porque normalizamos qualquer string com soDigitos, inclusive 529 982 247 25.
aria-invalid e aria-describedby fazem o leitor de tela anunciar o erro.

4. E o cursor?

Como a máscara insere caracteres, editar no meio pode empurrar o cursor. Para a maioria dos formulários isso é aceitável, porque as pessoas digitam CPF do início ao fim. Se o seu caso exige edição no meio, calcule quantos dígitos estavam antes do cursor e reposicione em um useLayoutEffect. Ou use uma biblioteca madura como react-imask.

5. React Hook Form + Zod

Em formulários maiores, centralize a regra no schema:

import { z } from "zod";

const schema = z.object({
  nome: z.string().min(3),
  cpf: z
    .string()
    .transform((s) => s.replace(/\D/g, ""))
    .refine(cpfValido, "CPF inválido"),
});

O transform garante que o backend recebe só dígitos.

6. Nunca confie só no front

Tudo isso é UX. O backend tem que validar de novo, porque qualquer um pode chamar sua API sem passar pelo formulário. E consultar uma API de CPF direto do navegador expõe sua chave: faça a consulta a partir de um endpoint seu (route handler, function, backend).

7. Pré-preenchendo o nome

Um uso comum: quando o CPF fica válido, o front chama o seu backend, que consulta uma API de CPF e devolve o primeiro nome para confirmação ("Você é Maria?"). Isso reduz digitação e erro. Mostre só o necessário e nunca a data de nascimento completa antes de a pessoa confirmar a identidade.

Sobre a CPFHub

Para esse backend, a CPFHub tem GET /cpf/{cpf} (header x-api-key), que retorna nome, gênero e data de nascimento em ~150 ms típicos (não SLA), com 50 créditos grátis por mês. Detalhes na documentação.

Higienizando uma base de CPFs em Python com pandas: validação vetorizada, duplicados e consulta em lote

CPFHub — Tue, 13 Oct 2026 04:27:01 +0000

Transparência: sou fundador da CPFHub, citada no final como opção para a etapa de consulta. As etapas de limpeza não dependem de nenhum serviço.

Toda empresa tem aquela planilha de clientes exportada do sistema antigo: CPF com máscara, sem máscara, com zero à esquerda perdido pelo Excel, duplicado, ou simplesmente 000.000.000-00. Antes de migrar ou de usar essa base para qualquer coisa, vale limpá-la. Vamos fazer isso com pandas.

1. Carregue como texto

O erro número um é deixar o pandas inferir o tipo. 01234567890 vira 1234567890.

import pandas as pd

df = pd.read_csv("clientes.csv", dtype={"cpf": "string"}, encoding="utf-8")

Se a coluna já veio numérica de um Excel, recupere o zero à esquerda depois de normalizar com zfill(11), mas só quando o tamanho for 10 (ou 9): mais que isso é dado corrompido.

2. Normalize

df["cpf_limpo"] = df["cpf"].str.replace(r"\D", "", regex=True)
mask_curto = df["cpf_limpo"].str.len().between(9, 10)
df.loc[mask_curto, "cpf_limpo"] = df.loc[mask_curto, "cpf_limpo"].str.zfill(11)

3. Valide de forma vetorizada

Aplicar uma função Python linha a linha funciona, mas com milhões de linhas é lento. Dá para calcular os dígitos verificadores com NumPy:

import numpy as np

def cpf_valido_vec(s: pd.Series) -> pd.Series:
    ok_len = s.str.len() == 11
    s11 = s.where(ok_len, "00000000000")
    d = np.array([list(map(int, x)) for x in s11], dtype=np.int64)
    p1 = np.arange(10, 1, -1)       # 10..2
    p2 = np.arange(11, 1, -1)       # 11..2
    dv1 = (d[:, :9] @ p1) * 10 % 11 % 10
    dv2 = (d[:, :10] @ p2) * 10 % 11 % 10
    repetido = (d == d[:, [0]]).all(axis=1)
    return ok_len & (d[:, 9] == dv1) & (d[:, 10] == dv2) & ~repetido

df["cpf_valido"] = cpf_valido_vec(df["cpf_limpo"].fillna(""))

A multiplicação de matriz (@) calcula a soma ponderada de todas as linhas de uma vez. Em uma base de 1 milhão de linhas, a diferença em relação a apply é grande.

Confira com casos conhecidos:

teste = pd.Series(["52998224725", "11111111111", "52998224724", "123"])
print(cpf_valido_vec(teste).tolist())  # [True, False, False, False]

4. Duplicados

dups = df[df.duplicated("cpf_limpo", keep=False) & df["cpf_valido"]]
print(f"{dups['cpf_limpo'].nunique()} CPFs aparecem mais de uma vez")

Para decidir qual registro manter, ordene por data de atualização e use drop_duplicates(keep="last"). Não apague nada da base original: gere um arquivo de saída e um relatório.

5. Relatório

resumo = {
    "total": len(df),
    "validos": int(df["cpf_valido"].sum()),
    "invalidos": int((~df["cpf_valido"]).sum()),
    "duplicados": int(dups["cpf_limpo"].nunique()),
}
print(resumo)
df[~df["cpf_valido"]].to_csv("cpfs_invalidos.csv", index=False)

O arquivo de inválidos vai para o time que pode corrigir na origem.

6. Confirmando existência em lote

O DV só garante formato. Se a base vai ser usada para crédito, faturamento ou comunicação, você provavelmente quer saber quais CPFs existem e se o nome bate. Fazer isso CPF a CPF em uma base grande esbarra em limite por minuto. O caminho mais limpo é um endpoint de lote.

Na CPFHub, por exemplo, existe POST /cpf/bulk, que aceita até 10.000 CPFs por requisição e processa em segundo plano. O fluxo fica assim (detalhes na documentação):

import os, requests

validos = df.loc[df["cpf_valido"], "cpf_limpo"].unique().tolist()
lotes = [validos[i:i + 10_000] for i in range(0, len(validos), 10_000)]

for lote in lotes:
    r = requests.post(
        "https://api.cpfhub.io/cpf/bulk",
        headers={"x-api-key": os.environ["CPFHUB_API_KEY"]},
        json={"cpfs": lote},
        timeout=60,
    )
    r.raise_for_status()
    job_id = r.json()["data"]["jobId"]   # resposta 202
    print("lote enfileirado:", job_id)

Depois, faça polling em GET /cpf/bulk/{jobId} até data.status ser done ou failed. CPFs inválidos são descartados e repetidos são consultados uma vez, mas é melhor limpar antes. Um detalhe importante: o POST não é idempotente, então não repita o envio depois de um timeout sem conferir se o lote já foi criado.

Mande apenas os CPFs válidos e únicos: você não paga por erro de digitação nem por duplicado.

7. Comparando nomes

Com o resultado em mãos, faça o merge e compare nomes normalizados:

import unicodedata

def norm(n):
    n = unicodedata.normalize("NFKD", str(n)).encode("ascii", "ignore").decode()
    return " ".join(n.upper().split())

res["nome_confere"] = res["nome_base"].map(norm) == res["name"].map(norm)

Divergências não são necessariamente fraude: nome de casada, abreviação e erro de digitação são comuns. Separe para revisão.

8. LGPD

Higienizar base é tratamento de dado pessoal. Tenha a finalidade clara, rode o processo em ambiente controlado, não espalhe cópias do CSV e apague os arquivos intermediários ao final.

Sobre a CPFHub

A CPFHub cobra 1 crédito por CPF encontrado no lote (não encontrado não consome) e tem 50 créditos grátis por mês para testar o fluxo com uma amostra antes de rodar a base inteira.

Validando e consultando CPF em Go: pacote enxuto, context e testes table-driven

CPFHub — Tue, 13 Oct 2026 04:17:00 +0000

Transparência: sou fundador da CPFHub, uma das APIs citadas no final. O pacote de validação é independente.

Go é ótimo para serviços de backend que recebem cadastro em alto volume. Vamos escrever um pacote cpf pequeno, sem dependências, e um cliente HTTP que respeita context, timeout e limites de taxa.

1. O pacote

package cpf

import "strings"

// Normalize remove tudo que não for dígito ASCII.
func Normalize(s string) string {
    var b strings.Builder
    for _, r := range s {
        if r >= '0' && r <= '9' {
            b.WriteRune(r)
        }
    }
    return b.String()
}

// Valid confere tamanho, sequência repetida e dígitos verificadores.
func Valid(s string) bool {
    c := Normalize(s)
    if len(c) != 11 || strings.Count(c, c[:1]) == 11 {
        return false
    }
    for t := 9; t < 11; t++ {
        sum := 0
        for i := 0; i < t; i++ {
            sum += int(c[i]-'0') * (t + 1 - i)
        }
        if int(c[t]-'0') != sum*10%11%10 {
            return false
        }
    }
    return true
}

// Format aplica a máscara 000.000.000-00.
func Format(s string) string {
    c := Normalize(s)
    if len(c) != 11 {
        return s
    }
    return c[:3] + "." + c[3:6] + "." + c[6:9] + "-" + c[9:]
}

2. Testes table-driven

func TestValid(t *testing.T) {
    cases := []struct {
        in   string
        want bool
    }{
        {"529.982.247-25", true},
        {"52998224725", true},
        {"11111111111", false},
        {"52998224724", false},
        {"", false},
    }
    for _, c := range cases {
        if got := Valid(c.in); got != c.want {
            t.Errorf("Valid(%q) = %v, want %v", c.in, got, c.want)
        }
    }
}

Vale adicionar um fuzz test (go test -fuzz) garantindo que Valid nunca entra em pânico com entrada arbitrária.

3. Cliente HTTP

Depois que o DV passa, uma API externa confirma se o CPF existe. Um cliente idiomático:

type Data struct {
    CPF       string `json:"cpf"`
    Name      string `json:"name"`
    Gender    string `json:"gender"`
    BirthDate string `json:"birthDate"`
}

var ErrNotFound = errors.New("cpf não encontrado")

type RateLimitError struct{ RetryAfter string }

func (e RateLimitError) Error() string { return "limite por minuto; retry-after " + e.RetryAfter }

type Client struct {
    HTTP   *http.Client
    APIKey string
}

func (c *Client) Lookup(ctx context.Context, raw string) (*Data, error) {
    n := cpf.Normalize(raw)
    if !cpf.Valid(n) {
        return nil, errors.New("cpf inválido")
    }
    req, _ := http.NewRequestWithContext(ctx, http.MethodGet,
        "https://api.cpfhub.io/cpf/"+n, nil)
    req.Header.Set("x-api-key", c.APIKey)

    res, err := c.HTTP.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()

    switch res.StatusCode {
    case http.StatusOK:
        var body struct {
            Success bool `json:"success"`
            Data    Data `json:"data"`
        }
        if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
            return nil, err
        }
        return &body.Data, nil
    case http.StatusNotFound:
        return nil, ErrNotFound
    case http.StatusTooManyRequests:
        return nil, RateLimitError{res.Header.Get("Retry-After")}
    default:
        return nil, fmt.Errorf("status %d", res.StatusCode)
    }
}

Uso:

c := &Client{HTTP: &http.Client{Timeout: 10 * time.Second}, APIKey: os.Getenv("CPFHUB_API_KEY")}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
d, err := c.Lookup(ctx, "529.982.247-25")
switch {
case errors.Is(err, ErrNotFound):
    // trate como resultado normal
case err != nil:
    var rl RateLimitError
    if errors.As(err, &rl) { /* reagende */ }
}

4. Controlando a taxa do seu lado

Toda API tem limite por minuto. Em vez de descobrir isso tomando 429, limite antes com golang.org/x/time/rate:

lim := rate.NewLimiter(rate.Every(2*time.Second), 1) // 30/min
for _, doc := range docs {
    if err := lim.Wait(ctx); err != nil { break }
    go process(doc)
}

Para listas grandes, prefira um endpoint de lote se o provedor tiver: uma requisição em vez de milhares.

5. Dicas

Nunca logue o CPF completo; use Format com mascaramento (***.982.247-**) nos logs.
Use errors.Is/As em vez de comparar strings de erro.
Não reutilize http.DefaultClient: ele não tem timeout.

Sobre a CPFHub

O cliente acima já está apontado para a CPFHub: GET /cpf/{cpf} com x-api-key, ~150 ms típicos (não SLA), 404 sem custo, e um POST /cpf/bulk para listas de até 10.000 CPFs. O plano gratuito tem 50 créditos por mês. Mais na documentação.

CPF em C# e .NET: validação, FluentValidation e consulta com HttpClient tipado

CPFHub — Tue, 13 Oct 2026 04:07:01 +0000

Transparência: sou fundador da CPFHub, citada no final como uma das opções. A validação mostrada aqui não depende de nenhum fornecedor.

Em projetos .NET brasileiros, CPF aparece em cadastro, emissão de nota, integração com ERP e onboarding. Este guia cobre: uma função de validação sem alocações desnecessárias, a regra no FluentValidation e uma consulta HTTP com IHttpClientFactory e Polly.

1. Validação com `ReadOnlySpan<char>`

public static class Cpf
{
    public static string Normalizar(string? s) =>
        new string((s ?? "").Where(char.IsAsciiDigit).ToArray());

    public static bool Valido(string? entrada)
    {
        var cpf = Normalizar(entrada).AsSpan();
        if (cpf.Length != 11) return false;

        bool todosIguais = true;
        for (int i = 1; i < 11; i++) if (cpf[i] != cpf[0]) { todosIguais = false; break; }
        if (todosIguais) return false;

        for (int t = 9; t < 11; t++)
        {
            int soma = 0;
            for (int i = 0; i < t; i++) soma += (cpf[i] - '0') * (t + 1 - i);
            int dv = soma * 10 % 11 % 10;
            if (cpf[t] - '0' != dv) return false;
        }
        return true;
    }
}

Use char.IsAsciiDigit (NET 7+) em vez de char.IsDigit: o segundo aceita dígitos de outros alfabetos, como os arábico-índicos, que não fazem sentido aqui.

2. FluentValidation

public class CadastroValidator : AbstractValidator<CadastroDto>
{
    public CadastroValidator()
    {
        RuleFor(x => x.Nome).NotEmpty().MaximumLength(120);
        RuleFor(x => x.Cpf)
            .NotEmpty()
            .Must(Cpf.Valido).WithMessage("CPF inválido");
    }
}

Se você usa Data Annotations, crie um ValidationAttribute chamando o mesmo Cpf.Valido. O importante é ter uma implementação, testada, usada em todo lugar.

3. Persistência

No EF Core, guarde só dígitos e garanta unicidade:

modelBuilder.Entity<Cliente>()
    .Property(c => c.Cpf).HasMaxLength(11).IsFixedLength();
modelBuilder.Entity<Cliente>()
    .HasIndex(c => c.Cpf).IsUnique();

char(11) comunica a intenção e evita que alguém grave com máscara.

4. HttpClient tipado

O DV garante formato. Para saber se o CPF existe e obter nome e data de nascimento, você precisa de uma API. Registre um client tipado:

builder.Services.AddHttpClient<CpfClient>(c =>
{
    c.BaseAddress = new Uri("https://api.cpfhub.io/");
    c.Timeout = TimeSpan.FromSeconds(10);
    c.DefaultRequestHeaders.Add("x-api-key", builder.Configuration["CpfHub:ApiKey"]);
});

public record CpfData(string Cpf, string Name, string Gender, string BirthDate);
public record CpfResponse(bool Success, CpfData? Data);

public class CpfClient(HttpClient http)
{
    public async Task<CpfData?> ConsultarAsync(string cpf, CancellationToken ct = default)
    {
        var limpo = Cpf.Normalizar(cpf);
        if (!Cpf.Valido(limpo)) throw new ArgumentException("CPF inválido");

        using var res = await http.GetAsync($"cpf/{limpo}", ct);
        switch ((int)res.StatusCode)
        {
            case 200:
                var body = await res.Content.ReadFromJsonAsync<CpfResponse>(
                    new JsonSerializerOptions(JsonSerializerDefaults.Web), ct);
                return body?.Data;
            case 404:
                return null; // não encontrado
            case 429:
                var retry = res.Headers.RetryAfter?.Delta;
                throw new LimiteException(retry);
            default:
                res.EnsureSuccessStatusCode();
                return null;
        }
    }
}

JsonSerializerDefaults.Web faz o binding case-insensitive (name → Name).

5. Polly: retry só no que faz sentido

Com Microsoft.Extensions.Http.Resilience (.NET 8):

builder.Services.AddHttpClient<CpfClient>(...)
    .AddStandardResilienceHandler(o =>
    {
        o.Retry.MaxRetryAttempts = 2;
        o.Retry.ShouldHandle = args => ValueTask.FromResult(
            args.Outcome.Result?.StatusCode is HttpStatusCode.BadGateway
                or HttpStatusCode.ServiceUnavailable);
    });

Não repita 401, 403 e 404: o resultado não muda. Para 429, respeite o Retry-After em vez de tentar de novo na hora.

6. Não guarde mais do que precisa

A LGPD pede minimização. Se você só precisa confirmar que o nome bate, guarde o resultado da verificação (ok/divergente e data), não necessariamente todos os campos retornados.

7. Testes

[Theory]
[InlineData("529.982.247-25", true)]
[InlineData("11111111111", false)]
[InlineData("52998224724", false)]
public void Valida(string cpf, bool esperado) => Assert.Equal(esperado, Cpf.Valido(cpf));

Para o CpfClient, injete um HttpMessageHandler falso que devolve 200, 404 e 429.

Sobre a CPFHub

A CPFHub é uma das APIs que você pode plugar no CpfClient: GET /cpf/{cpf} com x-api-key, ~150 ms de tempo típico (não SLA), 404 sem consumo de crédito e 50 créditos grátis por mês. Veja a documentação.

Validação de CPF em Java com Spring Boot: anotação customizada e cliente HTTP resiliente

CPFHub — Tue, 13 Oct 2026 03:56:59 +0000

Transparência: sou fundador da CPFHub, citada no final como uma opção de API. O resto do artigo vale para qualquer provedor.

Em Spring Boot, o lugar natural para validar CPF é o Bean Validation (Jakarta Validation). Assim a regra fica declarada no DTO, aparece no erro 400 padronizado e não se espalha por controllers. Vamos fazer isso e depois plugar uma consulta externa com timeout e tratamento de erros.

1. O algoritmo

public final class CpfUtils {
    private CpfUtils() {}

    public static String normalizar(String cpf) {
        return cpf == null ? "" : cpf.replaceAll("\\D", "");
    }

    public static boolean valido(String entrada) {
        String cpf = normalizar(entrada);
        if (cpf.length() != 11 || cpf.chars().distinct().count() == 1) return false;
        for (int t = 9; t < 11; t++) {
            int soma = 0;
            for (int i = 0; i < t; i++) {
                soma += (cpf.charAt(i) - '0') * ((t + 1) - i);
            }
            int dv = (soma * 10) % 11 % 10;
            if (cpf.charAt(t) - '0' != dv) return false;
        }
        return true;
    }
}

cpf.chars().distinct().count() == 1 elimina 00000000000, 11111111111 etc., que passam no cálculo mas não existem.

2. A anotação `@Cpf`

@Documented
@Constraint(validatedBy = CpfValidator.class)
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface Cpf {
    String message() default "CPF inválido";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

public class CpfValidator implements ConstraintValidator<Cpf, String> {
    @Override
    public boolean isValid(String value, ConstraintValidatorContext ctx) {
        if (value == null || value.isBlank()) return true; // deixe @NotBlank cuidar disso
        return CpfUtils.valido(value);
    }
}

Repare que nulo retorna true. É a convenção do Bean Validation: cada anotação valida uma coisa só, e obrigatoriedade é papel do @NotBlank.

public record CadastroRequest(
    @NotBlank String nome,
    @NotBlank @Cpf String cpf,
    @Email String email
) {}

@PostMapping("/clientes")
public ResponseEntity<?> criar(@Valid @RequestBody CadastroRequest req) { ... }

Com @Valid, um CPF inválido gera MethodArgumentNotValidException e o Spring devolve 400 sem você escrever um if.

3. Normalize antes de persistir

Use um setter, um @PrePersist ou o próprio service para gravar só dígitos. E crie índice único na coluna. Se o banco tiver 529.982.247-25 e 52998224725, você tem duplicidade invisível.

4. Consulta externa com `RestClient`

O DV prova formato, não existência. Se o seu fluxo precisa confirmar que o CPF existe e pegar nome e data de nascimento, chame uma API só depois que o DV passar.

No Spring Boot 3.2+ o RestClient é síncrono e simples:

@Component
public class CpfClient {
    private final RestClient http;

    public CpfClient(@Value("${cpfhub.api-key}") String apiKey) {
        var factory = new SimpleClientHttpRequestFactory();
        factory.setConnectTimeout(3_000);
        factory.setReadTimeout(10_000);
        this.http = RestClient.builder()
            .baseUrl("https://api.cpfhub.io")
            .defaultHeader("x-api-key", apiKey)
            .requestFactory(factory)
            .build();
    }

    public Optional<Map<String, Object>> consultar(String cpf) {
        String limpo = CpfUtils.normalizar(cpf);
        if (!CpfUtils.valido(limpo)) throw new IllegalArgumentException("CPF inválido");
        try {
            Map<?, ?> body = http.get().uri("/cpf/{cpf}", limpo)
                .retrieve().body(Map.class);
            return Optional.ofNullable((Map<String, Object>) body.get("data"));
        } catch (HttpClientErrorException.NotFound e) {
            return Optional.empty();              // não encontrado
        } catch (HttpClientErrorException.TooManyRequests e) {
            String retry = e.getResponseHeaders().getFirst("Retry-After");
            throw new LimiteException(retry);     // trate no caller
        }
    }
}

Boas práticas que valem para qualquer provedor:

Timeout explícito. O default do SimpleClientHttpRequestFactory é infinito.
404 não é exceção de negócio, é resposta. Devolva Optional.empty().
429 deve respeitar Retry-After. Não faça retry imediato em loop.
401/403 não devem ser repetidos: é chave errada ou falta de crédito.

5. Resiliência com Resilience4j

Se a consulta estiver no caminho crítico do cadastro, proteja com circuit breaker e um fallback que não bloqueia o usuário: grava o cadastro como "pendente de verificação" e reprocessa depois.

@CircuitBreaker(name = "cpf", fallbackMethod = "pendente")
public Resultado verificar(String cpf) { ... }

private Resultado pendente(String cpf, Throwable t) {
    return Resultado.PENDENTE;
}

Assim, se o provedor cair, sua conversão não cai junto.

6. Testes

Teste o validador com casos de borda:

@ParameterizedTest
@CsvSource({"529.982.247-25,true", "52998224725,true", "11111111111,false",
            "52998224724,false", "123,false"})
void valida(String cpf, boolean esperado) {
    assertEquals(esperado, CpfUtils.valido(cpf));
}

Para o cliente HTTP, use MockRestServiceServer ou WireMock e simule 200, 404 e 429. Nunca rode testes automatizados contra a API real com CPFs de pessoas.

Sobre a CPFHub

Se quiser testar o cliente acima, a CPFHub expõe GET https://api.cpfhub.io/cpf/{cpf} com header x-api-key, retornando nome, gênero e data de nascimento em ~150 ms (típico, não SLA). CPF não encontrado não consome crédito, e o plano gratuito tem 50 créditos por mês. Endpoints e códigos de erro estão na documentação.

Resumo

@Cpf no DTO, normalização antes de persistir, índice único, cliente HTTP com timeout e tratamento de 404/429, circuit breaker com fallback "pendente". Com isso o CPF deixa de ser uma fonte de dados sujos no seu sistema.

Como consultar CPF via API em Node.js e Python

CPFHub — Tue, 13 Oct 2026 03:25:55 +0000

Transparência: sou fundador da CPFHub, a API usada nos exemplos. Os conceitos (validação local, tratamento de erros, LGPD) valem para qualquer API de consulta de CPF.

Se você tem um formulário de cadastro, um checkout ou um backoffice no Brasil, cedo ou tarde precisa conferir se o CPF digitado existe e bate com o nome informado. Neste tutorial mostro como usar uma API de consulta de CPF em Node.js e Python: validar os dígitos localmente, fazer a consulta, tratar erros e decidir quando vale a pena consultar a Receita Federal em tempo real.

O que uma API de consulta de CPF retorna

Na consulta simples você envia o CPF e recebe os dados cadastrais básicos do titular:

nome completo (name e nameUpper, em maiúsculas, bom para comparar);
gênero (gender: "M", "F" ou null quando a base não tem a informação);
data de nascimento (birthDate no formato DD/MM/AAAA, mais day, month e year separados, úteis para calcular idade).

Exemplo de resposta (dados fictícios):

{
  "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
  }
}

Passo 1: valide os dígitos antes de chamar a API

Todo CPF tem dois dígitos verificadores calculados pelo módulo 11. Validar isso localmente é gratuito, instantâneo e evita requisições inúteis (CPF digitado errado, tudo repetido como 111.111.111-11 etc.).

Node.js:

function cpfValido(entrada) {
  const cpf = String(entrada).replace(/\D/g, "");
  if (cpf.length !== 11 || /^(\d)\1{10}$/.test(cpf)) return false;

  const digito = (base) => {
    let soma = 0;
    for (let i = 0; i < base.length; i++) {
      soma += Number(base[i]) * (base.length + 1 - i);
    }
    const resto = (soma * 10) % 11;
    return resto === 10 ? 0 : resto;
  };

  const d1 = digito(cpf.slice(0, 9));
  const d2 = digito(cpf.slice(0, 10));
  return d1 === Number(cpf[9]) && d2 === Number(cpf[10]);
}

Python:

import re

def cpf_valido(entrada: str) -> bool:
    cpf = re.sub(r"\D", "", str(entrada))
    if len(cpf) != 11 or cpf == cpf[0] * 11:
        return False

    def digito(base: str) -> int:
        soma = sum(int(n) * (len(base) + 1 - i) for i, n in enumerate(base))
        resto = (soma * 10) % 11
        return 0 if resto == 10 else resto

    return digito(cpf[:9]) == int(cpf[9]) and digito(cpf[:10]) == int(cpf[10])

Atenção: dígito válido não significa que o CPF existe ou pertence a quem digitou. Para isso serve a consulta.

Passo 2: consulta simples (GET)

Na CPFHub, a consulta simples é GET https://api.cpfhub.io/cpf/{cpf}, autenticada pelo header x-api-key. O CPF pode ir com ou sem máscara. Custa 1 crédito por CPF encontrado; CPF não encontrado (404) não consome crédito. O tempo típico é de ~150 ms (tempo típico, não SLA), e a documentação recomenda timeout de cerca de 10 s.

Os erros que você deve tratar:

Status	Significado	O que fazer
400	CPF sem 11 dígitos	Corrigir, não repetir
401	API Key ausente ou inválida	Conferir o header `x-api-key`
403	Créditos esgotados ou conta bloqueada	Recarregar créditos, não repetir
404	CPF não encontrado na base	Resultado normal
422	Dígito verificador inválido	Corrigir, não repetir
429	Limite por minuto (30/min no padrão)	Esperar o header `Retry-After`
500/503	Falha passageira	Repetir com espera crescente

Um detalhe: em erros de autenticação o campo error vem como string; nos demais, como objeto com message. Leia os dois formatos.

Node.js (18+, fetch nativo):

const API_KEY = process.env.CPFHUB_API_KEY; // nunca no front-end

async function consultarCpf(cpf) {
  if (!cpfValido(cpf)) throw new Error("CPF inválido (dígitos)");

  const res = await fetch(`https://api.cpfhub.io/cpf/${cpf.replace(/\D/g, "")}`, {
    headers: { "x-api-key": API_KEY },
    signal: AbortSignal.timeout(10_000),
  });
  const body = await res.json().catch(() => ({}));
  const msg = typeof body.error === "string" ? body.error : body.error?.message;

  if (res.ok) return body.data;
  if (res.status === 404) return null; // não encontrado, sem custo
  if (res.status === 429) {
    throw new Error(`Limite por minuto; tente em ${res.headers.get("retry-after")} s`);
  }
  if (res.status === 403) throw new Error(`Sem créditos ou conta bloqueada: ${msg}`);
  throw new Error(`Erro ${res.status}: ${msg}`);
}

const dados = await consultarCpf("123.456.789-09");
console.log(dados?.name, dados?.gender, dados?.birthDate);

Python (requests):

import os
import requests

API_KEY = os.environ["CPFHUB_API_KEY"]

def consultar_cpf(cpf: str):
    if not cpf_valido(cpf):
        raise ValueError("CPF inválido (dígitos)")

    numero = "".join(c for c in cpf if c.isdigit())
    r = requests.get(
        f"https://api.cpfhub.io/cpf/{numero}",
        headers={"x-api-key": API_KEY},
        timeout=10,
    )
    try:
        body = r.json()
    except ValueError:
        body = {}
    err = body.get("error")
    msg = err if isinstance(err, str) else (err or {}).get("message")

    if r.ok:
        return body["data"]
    if r.status_code == 404:
        return None  # não encontrado, sem custo
    if r.status_code == 429:
        raise RuntimeError(f"Limite por minuto; tente em {r.headers.get('Retry-After')} s")
    if r.status_code == 403:
        raise RuntimeError(f"Sem créditos ou conta bloqueada: {msg}")
    raise RuntimeError(f"Erro {r.status_code}: {msg}")

dados = consultar_cpf("123.456.789-09")
if dados:
    print(dados["name"], dados["gender"], dados["birthDate"])

Se o timeout estourar do seu lado, lembre que a consulta pode ter sido concluída e cobrada no servidor; repetir cobra de novo.

Passo 3: consulta em tempo real na Receita Federal (POST)

Quando você precisa da situação cadastral ou de um comprovante, use POST https://api.cpfhub.io/cpf/realtime. Ela consulta a Receita Federal no momento da chamada e exige CPF + data de nascimento (DD/MM/AAAA ou DDMMAAAA). Custa 1,5 crédito por consulta bem-sucedida, em qualquer situação cadastral. O tempo típico é de cerca de 1 segundo (não é SLA), mas a documentação pede timeout de pelo menos 60 s.

A resposta traz name, birthDate, situation (REGULAR, PENDENTE DE REGULARIZAÇÃO, SUSPENSA, CANCELADA, NULA ou TITULAR FALECIDO), deathYear e, quando disponíveis, controlCode, emissionDate, emissionTime, validationUrl (conferência no site da Receita) e validationHtmlUrl (comprovante).

Sobre deathYear: o campo sempre vem, como inteiro ou null. null significa que não há óbito registrado (ou o valor recebido era inválido). Não trate null como prova de que a pessoa está viva. E só REGULAR indica CPF sem pendências.

Node.js:

async function consultarReceita(cpf, dataNascimento) {
  const res = await fetch("https://api.cpfhub.io/cpf/realtime", {
    method: "POST",
    headers: { "x-api-key": API_KEY, "content-type": "application/json" },
    body: JSON.stringify({ cpf, birthDate: dataNascimento }),
    signal: AbortSignal.timeout(60_000),
  });
  const body = await res.json().catch(() => ({}));
  if (res.ok) return body.data; // { situation, deathYear, controlCode, ... }
  // 422: dígito inválido ou a Receita recusou (ex.: data divergente) — sem custo
  // 429: 5/min no padrão; 502/503: repetir com espera crescente — sem custo
  const msg = typeof body.error === "string" ? body.error : body.error?.message;
  throw new Error(`Erro ${res.status}: ${msg}`);
}

Python:

def consultar_receita(cpf: str, data_nascimento: str):
    r = requests.post(
        "https://api.cpfhub.io/cpf/realtime",
        headers={"x-api-key": API_KEY},
        json={"cpf": cpf, "birthDate": data_nascimento},
        timeout=60,
    )
    body = r.json() if r.content else {}
    if r.ok:
        return body["data"]
    err = body.get("error")
    msg = err if isinstance(err, str) else (err or {}).get("message")
    raise RuntimeError(f"Erro {r.status_code}: {msg}")

d = consultar_receita("12345678909", "15/06/1990")
print(d["situation"], d["deathYear"])

Duas cautelas: o POST não é idempotente, então depois de um timeout local confira o saldo em GET /quota antes de repetir; e o link validationHtmlUrl é público (abre nome, CPF e situação), então guarde-o só no back-end e fora dos logs.

Quando usar cada consulta

Simples (1 crédito): confirmar nome, gênero e idade no cadastro ou checkout. Rápida e barata.
Tempo real (1,5 crédito): quando você precisa da situação cadastral na Receita ou de um comprovante (crédito, contratos, cadastro regulado).
Lote (POST /cpf/bulk, 1 crédito por CPF encontrado): listas de até 10.000 CPFs, processadas em segundo plano — por exemplo, higienizar uma base antiga.

O plano gratuito inclui 50 créditos por mês, sem cartão, o que dá para testar tudo isso. Detalhes de cada endpoint estão na documentação da CPFHub.

LGPD: consulte com finalidade

CPF e data de nascimento são dados pessoais. Antes de integrar qualquer API de consulta de CPF:

tenha uma finalidade legítima e uma base legal (ex.: execução de contrato, prevenção a fraude no cadastro);
não guarde mais do que precisa: se só precisa saber se o nome confere, guarde o resultado da checagem, não a resposta inteira;
mantenha a API Key e as respostas no back-end, e não registre CPFs completos em logs.

Bônus: consulta de CPF por agentes de IA (MCP)

Se você usa Claude, Cursor ou outro cliente MCP, a CPFHub tem um servidor MCP remoto em https://api.cpfhub.io/mcp (autenticado pelo mesmo x-api-key), com as tools lookup_cpf, lookup_cpf_realtime e get_quota_info. Para clientes sem suporte a HTTP existe o pacote local @cpfhub/mcp (via npx), que hoje só tem lookup_cpf funcionando.

Resumo

Valide os dígitos localmente.
Use a consulta simples para nome, gênero e data de nascimento.
Use a consulta em tempo real quando precisar da situação cadastral na Receita.
Trate 404 como resultado normal, respeite 429 e não repita POST depois de timeout.
Colete e guarde só o necessário.

Para testar, crie uma conta gratuita em cpfhub.io e gere sua chave. Dúvidas sobre a consulta CPF via API? Deixe nos comentários.

LGPD e consulta de CPF via API: finalidade, base legal e o que guardar

CPFHub — Tue, 13 Oct 2026 03:25:02 +0000

Transparência: sou fundador da CPFHub, uma API de consulta de CPF. Este artigo não é aconselhamento jurídico. É um guia prático para desenvolvedores; para o seu caso concreto, consulte um especialista.

Integrar uma API de consulta de CPF leva uma tarde. Integrar do jeito certo do ponto de vista da LGPD (Lei nº 13.709/2018) exige algumas decisões antes da primeira linha de código. Este guia reúne as perguntas que costumo ver em times de produto e engenharia e o que elas significam na prática.

Primeiro: quem é o controlador?

Quando sua aplicação consulta um CPF para decidir algo sobre um cliente, você é o controlador desses dados no contexto da sua aplicação: é você quem decide por que e como eles são tratados. O fornecedor da API atua no papel que o contrato e a política dele definirem. Isso importa porque as obrigações principais — ter base legal, informar o titular, atender pedidos de acesso e exclusão — recaem sobre quem decide a finalidade.

Finalidade antes de tudo

A LGPD exige finalidade legítima, específica e informada ao titular. Antes de integrar, escreva em uma frase por que você consulta o CPF. Exemplos que fazem sentido:

confirmar que o nome informado no cadastro corresponde ao CPF, para prevenir fraude;
verificar maioridade antes de liberar um serviço restrito;
conferir a situação cadastral na Receita antes de conceder crédito ou emitir um documento fiscal.

Exemplos que não fazem sentido: "enriquecer a base para marketing", "consultar todo mundo que visitou o site", "descobrir quem é o dono de um CPF qualquer". Se a frase não convence você, não vai convencer a ANPD.

Bases legais mais comuns

O art. 7º da LGPD lista as hipóteses que autorizam o tratamento. Para consulta de CPF, as mais usadas costumam ser:

Cumprimento de obrigação legal ou regulatória (art. 7º, II): empresas reguladas, como instituições financeiras e seguradoras, com obrigações de identificação de clientes e prevenção à lavagem de dinheiro.
Execução de contrato (art. 7º, V): validar os dados da pessoa que está contratando com você.
Legítimo interesse (art. 7º, IX): prevenção a fraude, segurança da plataforma e integridade do cadastro — de forma proporcional e transparente. Legítimo interesse pede uma avaliação documentada (o chamado teste de balanceamento): o seu interesse, a necessidade do dado e as expectativas do titular.

Consentimento é possível, mas costuma ser frágil para prevenção a fraude: o titular pode revogá-lo, e quem frauda não vai consentir.

Minimização: consulte e guarde só o necessário

O princípio da necessidade (art. 6º, III) é o que mais muda o código. Algumas regras práticas:

Escolha a consulta mínima. Se você só precisa confirmar nome e idade, uma consulta simples (nome, gênero, data de nascimento) basta. A consulta da situação cadastral na Receita só se justifica quando o status muda a decisão. Na CPFHub, por exemplo, a consulta simples custa 1 crédito e a em tempo real 1,5 — mas o argumento aqui não é custo, é coletar menos.

Guarde o resultado da checagem, não a resposta inteira. Em vez de persistir o JSON completo, grave algo como:

{ "cpf_verificado": true, "nome_confere": true, "verificado_em": "2026-10-12" }

Defina prazo de retenção. Mantenha os resultados só pelo tempo necessário para a finalidade (ou exigido por obrigação legal) e automatize a exclusão.

Não duplique dados em lugares esquecidos: logs de aplicação, ferramentas de observabilidade, execuções salvas de automações (n8n, Make, Zapier), planilhas exportadas e tickets de suporte.

Segurança: o básico que evita incidentes

A chave da API fica no servidor. Nunca no front-end, no app mobile ou no repositório. Chamada direta do navegador expõe a chave a qualquer um.
Não registre CPFs completos em logs. Mascare (123.***.***-09) ou use um hash quando precisar correlacionar eventos.
Comprovantes são dados pessoais. Algumas APIs devolvem links de comprovante da consulta que abrem nome, CPF e situação para quem tiver o link. Guarde-os só no back-end e nunca os envie ao cliente sem necessidade.
Controle de acesso interno. Nem todo mundo no time precisa consultar CPFs; restrinja quem pode disparar consultas manuais.

Transparência com o titular

Informe na sua política de privacidade que os dados cadastrais podem ser verificados junto a provedores de validação de identidade e prevenção a fraudes, qual a finalidade e por quanto tempo os resultados ficam guardados. Uma linha no formulário de cadastro ("Vamos conferir seu CPF para proteger sua conta") ajuda a alinhar expectativas.

Direitos do titular

O titular pode pedir acesso, correção e exclusão dos dados que você armazena. Se você seguiu a minimização, a resposta é simples: "guardamos que seu CPF foi verificado em tal data". Tenha um processo (mesmo que manual) para atender esses pedidos no prazo.

Checklist para avaliar um fornecedor

De onde vêm os dados? (Base própria, fontes licenciadas, consulta à Receita em tempo real?)
O fornecedor vende listas ou usa as consultas para marketing?
Ele informa a um cliente quais CPFs outros clientes consultaram?
Há documentação de LGPD, termos de uso e política de privacidade públicos?
Quais dados ele não retorna? (Menos dados retornados = menos risco para você.)

Como referência, a página de Compliance & LGPD da CPFHub responde a essas perguntas para o nosso caso; peça o equivalente a qualquer fornecedor que avaliar.

Resumo

Escreva a finalidade em uma frase antes de integrar.
Escolha a base legal adequada e documente o legítimo interesse, se for o caso.
Use a consulta mínima e guarde o resultado da checagem, não a resposta.
Chave no servidor, CPF mascarado nos logs, comprovantes protegidos.
Seja transparente com o titular e tenha processo para atender pedidos.

Repetindo: isto é orientação geral, não aconselhamento jurídico. Para casos regulados ou de alto volume, envolva seu DPO ou um advogado especializado em proteção de dados.

DEV Community: CPFHub

Campo de CPF em React sem dor: máscara, validação em tempo real e acessibilidade

1. Guarde dígitos, mostre máscara

2. Validação dos dígitos

3. O componente

4. E o cursor?

5. React Hook Form + Zod

6. Nunca confie só no front

7. Pré-preenchendo o nome

Sobre a CPFHub

Higienizando uma base de CPFs em Python com pandas: validação vetorizada, duplicados e consulta em lote

1. Carregue como texto

2. Normalize

3. Valide de forma vetorizada

4. Duplicados

5. Relatório

6. Confirmando existência em lote

7. Comparando nomes

8. LGPD

Sobre a CPFHub

Validando e consultando CPF em Go: pacote enxuto, context e testes table-driven

1. O pacote

2. Testes table-driven

3. Cliente HTTP

4. Controlando a taxa do seu lado

5. Dicas

Sobre a CPFHub

CPF em C# e .NET: validação, FluentValidation e consulta com HttpClient tipado

1. Validação com ReadOnlySpan<char>

2. FluentValidation

3. Persistência

4. HttpClient tipado

5. Polly: retry só no que faz sentido

6. Não guarde mais do que precisa

7. Testes

Sobre a CPFHub

Validação de CPF em Java com Spring Boot: anotação customizada e cliente HTTP resiliente

1. O algoritmo

2. A anotação @Cpf

3. Normalize antes de persistir

4. Consulta externa com RestClient

5. Resiliência com Resilience4j

6. Testes

Sobre a CPFHub

Resumo

Como consultar CPF via API em Node.js e Python

O que uma API de consulta de CPF retorna

Passo 1: valide os dígitos antes de chamar a API

Passo 2: consulta simples (GET)

Passo 3: consulta em tempo real na Receita Federal (POST)

Quando usar cada consulta

LGPD: consulte com finalidade

Bônus: consulta de CPF por agentes de IA (MCP)

Resumo

LGPD e consulta de CPF via API: finalidade, base legal e o que guardar

Primeiro: quem é o controlador?

Finalidade antes de tudo

Bases legais mais comuns

Minimização: consulte e guarde só o necessário

Segurança: o básico que evita incidentes

Transparência com o titular

Direitos do titular

Checklist para avaliar um fornecedor

Resumo

1. Validação com `ReadOnlySpan<char>`

2. A anotação `@Cpf`

4. Consulta externa com `RestClient`