API de CPF: como funciona a consulta por faixa etária e gênero

A API de CPF retorna, além do nome do titular, a data de nascimento (dividida em dia, mês e ano) e o gênero — campos que permitem verificar maioridade, segmentar usuários por faixa etária e detectar inconsistências cadastrais automaticamente. Cada consulta ao endpoint GET https://api.cpfhub.io/cpf/{CPF} devolve esses dados em tempo real, com latência média de ~900ms. De acordo com a Receita Federal, o CPF concentra os registros cadastrais oficiais de pessoas físicas no Brasil, tornando esses dados a fonte mais confiável para validação de identidade.

Dados retornados pela API

A resposta da API inclui os seguintes campos relacionados a idade e gênero:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Ana Paula Ferreira",
    "nameUpper": "ANA PAULA FERREIRA",
    "gender": "F",
    "birthDate": "22/08/1992",
    "day": 22,
    "month": 8,
    "year": 1992
    }
}

Os campos day, month e year facilitam o cálculo de idade sem necessidade de parsear a string birthDate.

Verificação de maioridade

Um dos usos mais comuns dos dados de data de nascimento é a verificação de maioridade. Plataformas de apostas, e-commerces de bebidas alcoólicas e serviços financeiros precisam confirmar que o usuário tem 18 anos ou mais.

import requests
from datetime import date

def verificar_maioridade(cpf: str) -> dict:
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    headers = {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    }

    response = requests.get(url, headers=headers, timeout=10)
    resultado = response.json()

    if not resultado.get('success'):
    return {'maioridade': None, 'motivo': 'CPF nao encontrado'}

    dados = resultado['data']
    hoje = date.today()
    nascimento = date(dados['year'], dados['month'], dados['day'])
    idade = hoje.year - nascimento.year

    # Ajuste se ainda nao fez aniversario no ano
    if (hoje.month, hoje.day) < (nascimento.month, nascimento.day):
    idade -= 1

    return {
    'maioridade': idade >= 18,
    'idade': idade,
    'nome': dados['name'],
    'genero': dados['gender']
    }

resultado = verificar_maioridade('12345678900')
print(resultado)
# {'maioridade': True, 'idade': 33, 'nome': 'Ana Paula Ferreira', 'genero': 'F'}

Segmentação por faixa etária

Para aplicações de marketing, CRM e análise de dados, a segmentação por faixa etária permite personalizar a experiência do usuário.

def classificar_faixa_etaria(ano_nascimento: int) -> str:
    idade = date.today().year - ano_nascimento

    if idade < 18:
    return 'Menor de idade'
    elif idade <= 25:
    return '18-25'
    elif idade <= 35:
    return '26-35'
    elif idade <= 45:
    return '36-45'
    elif idade <= 55:
    return '46-55'
    elif idade <= 65:
    return '56-65'
    else:
    return '65+'

def enriquecer_cadastro(cpf: str) -> dict:
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    headers = {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    }

    response = requests.get(url, headers=headers, timeout=10)
    resultado = response.json()

    if not resultado.get('success'):
    return {'erro': 'CPF nao encontrado'}

    dados = resultado['data']

    return {
    'nome': dados['name'],
    'genero': dados['gender'],
    'faixa_etaria': classificar_faixa_etaria(dados['year']),
    'idade': date.today().year - dados['year']
    }

print(enriquecer_cadastro('12345678900'))
# {'nome': 'Ana Paula Ferreira', 'genero': 'F', 'faixa_etaria': '26-35', 'idade': 33}

Verificação de consistência de gênero

O campo gender pode ser usado para detectar inconsistências entre os dados informados pelo usuário e os registros oficiais. Essa verificação é útil em cenários de prevenção de fraudes.

async function verificarConsistencia(cpf, generoInformado) {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

    try {
    const response = await fetch(
    `https://api.cpfhub.io/cpf/${cpf}`,
    {
    headers: {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    signal: controller.signal
    }
    );

    clearTimeout(timeoutId);
    const resultado = await response.json();

    if (!resultado.success) {
    return { consistente: false, motivo: 'CPF nao encontrado' };
    }

    const generoOficial = resultado.data.gender;
    const generoConsistente = generoInformado.toUpperCase() === generoOficial;

    return {
    consistente: generoConsistente,
    generoInformado: generoInformado.toUpperCase(),
    generoOficial,
    motivo: generoConsistente ? 'Genero confere' : 'Genero divergente'
    };
    } catch (error) {
    clearTimeout(timeoutId);
    throw error;
    }
}

Casos de uso por setor

Plataformas de apostas e iGaming

A regulamentação brasileira exige que plataformas de apostas verifiquem a maioridade dos apostadores. A API permite confirmar a idade do titular do CPF com base em dados oficiais, não apenas com base na declaração do usuário.

E-commerce e marketplace

Lojas que vendem produtos com restrição de idade (bebidas, tabaco, armas de pressão) podem integrar a verificação de maioridade diretamente no checkout, bloqueando pedidos de menores de idade automaticamente.

Fintechs e bancos digitais

Instituições financeiras podem usar a faixa etária e o gênero para oferecer produtos personalizados, além de detectar tentativas de fraude quando os dados informados divergem dos registros oficiais.

Seguradoras

O cálculo de prêmios de seguro frequentemente considera idade e gênero. A API permite automatizar a coleta desses dados no momento da cotação, eliminando erros de preenchimento.

Análise de base de clientes

Com os dados de faixa etária e gênero, é possível gerar relatórios sobre a composição da base de clientes.

from collections import Counter

def analisar_base(lista_cpfs: list) -> dict:
    faixas = Counter()
    generos = Counter()

    headers = {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    }

    for cpf in lista_cpfs:
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    response = requests.get(url, headers=headers, timeout=10)
    resultado = response.json()

    if resultado.get('success'):
    dados = resultado['data']
    faixa = classificar_faixa_etaria(dados['year'])
    faixas[faixa] += 1
    generos[dados['gender']] += 1

    return {
    'faixas_etarias': dict(faixas),
    'generos': dict(generos),
    'total_consultados': len(lista_cpfs)
    }

Boas práticas

• Calcule a idade com precisão -- Use o dia e o mês para verificar se o titular já fez aniversário no ano corrente. Considerar apenas o ano pode gerar erros de até 1 ano.

• Não use gênero como fator de bloqueio -- Divergência de gênero pode ter explicações legítimas (atualização cadastral em andamento). Use como sinal de alerta, não como critério único de rejeição.

• Respeite a LGPD -- Os dados de faixa etária e gênero são dados pessoais. Use-os apenas para finalidades legítimas e declaradas ao titular.

• Cache os resultados -- Se você precisa consultar múltiplos CPFs para análise, implemente cache para evitar consultas duplicadas e respeitar os rate limits.

• Considere o plano adequado -- Para análises de base com muitos CPFs, o plano Pro (1.000 consultas/mês por R$ 149) ou o plano Corporativo são mais indicados.

Perguntas frequentes

Para que serve o campo gender retornado pela API de CPF?

O campo gender indica o gênero do titular cadastrado na Receita Federal (valor "M" para masculino ou "F" para feminino). Ele é útil para detectar inconsistências entre os dados declarados pelo usuário e o registro oficial, o que pode sinalizar tentativas de uso de CPF de terceiros. Como sinal de fraude, deve ser combinado com outras verificações — nunca usado como critério único de bloqueio.

Como calcular a idade a partir dos campos retornados pela API?

A API devolve day, month e year separadamente para facilitar o cálculo. Use os três campos para verificar se o titular já fez aniversário no ano corrente: subtraia o ano de nascimento do ano atual e, se o par mês/dia atual for anterior ao par mês/dia de nascimento, subtraia mais 1. Considerar apenas o ano gera erros de até 12 meses.

A API retorna dados de menores de idade?

Sim, a API retorna os dados do titular independentemente da idade. A verificação de maioridade é responsabilidade da aplicação consumidora: basta calcular a idade a partir dos campos retornados e decidir se permite ou bloqueia o fluxo. Para plataformas com restrições legais de idade — como apostas e iGaming —, essa verificação é obrigatória por regulamentação.

Quantas consultas posso fazer por mês para analisar minha base de clientes?

O plano gratuito oferece 50 consultas mensais sem cartão de crédito, ideal para testes. Para análises de base de clientes, o plano Pro (R$149/mês) inclui 1.000 consultas. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional. Para volumes maiores, o plano Corporativo oferece cota personalizada.

Conclusão

Os dados de faixa etária e gênero retornados pela API de CPF são ferramentas valiosas para verificação de maioridade, segmentação de público, prevenção de fraudes e compliance regulatório. A CPFHub.io

Cadastre-se em cpfhub.io