Como funciona a verificação de CPF via API em tempo real?

A verificação de CPF via API funciona com uma requisição HTTP GET autenticada: sua aplicação envia o número do CPF na URL e a chave de API no header, e o servidor retorna um JSON com nome, gênero e data de nascimento do titular em ~150 ms. Não há verificação manual nem acesso a portais governamentais — o processo é totalmente automatizado e acontece em tempo real.

Introdução

A verificação de CPF via API permite que sistemas, aplicações e plataformas consultem dados cadastrais associados a um número de CPF de forma automática, rápida e segura. Em vez de verificações manuais ou consultas a portais governamentais, uma simples requisição HTTP retorna os dados em ~150 ms (tempo típico da Consulta Simples, não é um SLA).

O que é uma API de consulta de CPF?

Uma API (Application Programming Interface) de consulta de CPF é um serviço web que recebe um número de CPF como entrada e retorna dados cadastrais associados a esse número. O processo é totalmente automatizado e acontece em tempo real.

Características principais:

• Comunicação via protocolo HTTPS (seguro).

• Formato de entrada e saída padronizado (JSON).

• Autenticação por chave de API.

• Resposta em ~150 ms (tempo típico, não é um SLA).

Como funciona o fluxo de consulta

1. Sua aplicação envia uma requisição

O sistema faz uma chamada HTTP GET ao endpoint da API, passando o CPF na URL e a chave de autenticação no header:

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json"

2. A API processa a consulta

O servidor da API recebe a requisição, valida a chave de API, verifica o formato do CPF e consulta a base de dados atualizada.

3. A API retorna os dados em JSON

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

4. Sua aplicação processa a resposta

Com os dados retornados, sua aplicação pode validar a identidade do usuário, preencher formulários automaticamente, cruzar informações ou tomar decisões de negócio.

Quais dados são retornados?

Qual o tempo de resposta?

A CPFHub.io opera com latência média de ~150 ms por consulta. Esse tempo inclui autenticação da chave de API, consulta à base de dados e serialização da resposta JSON. Para aplicações que precisam de resposta mais ágil na interface, recomenda-se implementar cache local para CPFs já consultados.

Como começar a usar

1. Crie uma conta gratuita em cpfhub.io

2. Gere sua chave de API no painel de controle.

3. Faça sua primeira requisição usando qualquer linguagem (Node.js, Python, PHP, Go, Ruby, Java, .NET, Rust, Elixir e mais).

4. Integre no seu sistema -- a documentação inclui exemplos em 13+ linguagens.

Códigos de resposta HTTP

No plano Grátis, os 50 créditos mensais esgotados pausam as consultas e a API responde HTTP 403 com "Limite de créditos excedido". Nos planos pagos o excedente, quando o plano inclui, é cobrado na fatura seguinte — os valores estão na página de preços. O limite por minuto é separado: HTTP 429 com Retry-After.

Casos de uso comuns

• Onboarding digital -- Validar identidade em cadastros de contas.

• E-commerce -- Confirmar dados do comprador no checkout.

• Fintechs -- KYC e prevenção a fraudes.

• Seguradoras -- Verificar dados do segurado.

• Marketplaces -- Validar vendedores e compradores.

Perguntas frequentes

Como funciona a autenticação na API de CPF?

A autenticação é feita via header HTTP x-api-key. Cada requisição deve incluir x-api-key: SUA_CHAVE_DE_API. Sem esse header, a API retorna HTTP 401. A chave é gerada no painel da CPFHub.io após o cadastro e deve ser armazenada como variável de ambiente — nunca no código-fonte.

Qual é a diferença entre validação e consulta de CPF?

Validação verifica se o número do CPF tem os dígitos verificadores corretos — pode ser feita localmente, sem API. Consulta vai além: verifica se o CPF existe na base e retorna os dados cadastrais do titular (nome, gênero, data de nascimento). Para confirmar identidade, é preciso consultar; para checar formato, basta validar.

O que acontece quando o limite do plano é atingido?

Sim, no Grátis. A cota de 50 créditos mensais, quando acaba, pausa as consultas com HTTP 403 e a mensagem "Limite de créditos excedido". Um plano pago pode continuar se tiver excedente — o valor está na página de preços — e o teto de chamadas por minuto responde HTTP 429 com Retry-After. Monitore o consumo no painel em app.cpfhub.io/settings/billing.

Como implementar cache para otimizar consultas de CPF?

O CERT.br recomenda que dados sensíveis armazenados em cache sejam protegidos com os mesmos controles de acesso dos dados originais. Para CPFs, o cache deve ter TTL curto (1 a 24 horas), ser armazenado com o CPF como chave e restrito ao serviço que fez a consulta. Isso reduz latência percebida e o número de consultas faturadas.

Conclusão

A verificação de CPF via API é um processo direto: uma requisição HTTP GET com o CPF na URL e a chave de API no header, e a resposta chega com nome, gênero e data de nascimento do titular em ~150 ms. A CPFHub.io oferece esse serviço com plano gratuito de 50 créditos mensais e plano Pro com 1.000 créditos por R$149. Quando os créditos do Grátis acabam, a API pausa e devolve HTTP 403, "Limite de créditos excedido". Se o plano for pago e tiver excedente, a cobrança extra sai na fatura seguinte — veja a página de preços. O teto por minuto, se estourado, responde HTTP 429 com Retry-After.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e faça sua primeira consulta de CPF em tempo real em menos de 5 minutos.