Como consultar situação cadastral do CPF via API (regular, suspensa, cancelada)

Para consultar a situação cadastral do CPF via API, faça uma requisição GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. Se success: true, o CPF foi localizado com dados cadastrais disponíveis; se success: false, o CPF pode estar em situação irregular ou inexistente. A Receita Federal classifica os CPFs como regular, suspenso, cancelado, pendente de regularização ou nulo — cada status tem implicações distintas para onboarding, emissão de notas e concessão de crédito.

Introdução

A situação cadastral do CPF junto à Receita Federal é uma informação crucial para diversos processos de negócio. Um CPF pode estar regular, suspenso, cancelado, pendente de regularização ou nulo, e cada um desses status tem implicações diferentes para transações comerciais, abertura de contas, emissão de documentos fiscais e processos de onboarding.

Consultar essa informação manualmente -- acessando o site da Receita Federal para cada CPF -- é inviável para empresas que precisam verificar dezenas ou centenas de CPFs por dia. A alternativa é utilizar uma API de consulta de CPF que automatiza esse processo e retorna os dados de forma estruturada.

As situações cadastrais do CPF

A Receita Federal classifica os CPFs nas seguintes situações:

Regular

O CPF está ativo e sem pendências. O titular pode realizar qualquer operação que exija CPF válido, como abrir contas, assinar contratos, realizar transações financeiras e emitir documentos fiscais.

Suspensa

O CPF foi suspenso pela Receita Federal, geralmente por inconsistências cadastrais ou ausência de declaração de imposto de renda por anos consecutivos. O titular precisa regularizar a situação para voltar a utilizar o CPF normalmente.

Cancelada

O CPF foi cancelado, o que geralmente ocorre em casos de duplicidade cadastral (quando uma pessoa possui mais de um CPF) ou por decisão administrativa da Receita Federal. CPFs cancelados não podem ser utilizados para fins legais.

Pendente de regularização

O CPF possui pendências que precisam ser resolvidas junto à Receita Federal. É uma situação intermediária entre regular e suspensa.

Nula

O CPF foi declarado nulo, geralmente por ter sido obtido de forma fraudulenta ou por erro administrativo. É a situação mais grave e irreversível.

Consultando dados de CPF via API

A API da CPFHub.io retorna os dados cadastrais do titular por meio de uma chamada GET simples:

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

A resposta retorna os dados cadastrais do titular:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Roberto Carlos Pereira",
    "nameUpper": "ROBERTO CARLOS PEREIRA",
    "gender": "M",
    "birthDate": "14/02/1975",
    "day": 14,
    "month": 2,
    "year": 1975
    }
}

Quando o CPF não é localizado ou apresenta problemas, o campo success retorna false, permitindo que sua aplicação trate o caso adequadamente.

Como tratar cada cenário na aplicação

CPF encontrado com sucesso

Quando a API retorna success: true, o CPF foi localizado e os dados cadastrais estão disponíveis. Sua aplicação pode prosseguir com o fluxo normal, utilizando os dados retornados para verificação cruzada.

CPF não encontrado

Quando success retorna false, o CPF pode estar em situação irregular ou ser inexistente. Nesse caso, recomenda-se:

• Solicitar verificação ao usuário -- Peça que o usuário confira o número digitado.
• Oferecer alternativa -- Sugira que o usuário consulte sua situação cadastral diretamente no site da Receita Federal.
• Registrar a ocorrência -- Mantenha um log para análise posterior.

Implementação de tratamento de respostas

import requests

def consultar_e_tratar_cpf(cpf: str, api_key: str) -> dict:
    """
    Consulta CPF e trata os diferentes cenários de resposta.
    """
    cpf_limpo = ''.join(filter(str.isdigit, cpf))

    if len(cpf_limpo) != 11:
    return {
    'status': 'formato_invalido',
    'mensagem': 'O CPF deve conter exatamente 11 dígitos.',
    'acao': 'Solicitar novo CPF ao usuário.'
    }

    url = f'https://api.cpfhub.io/cpf/{cpf_limpo}'
    headers = {
    'x-api-key': api_key,
    'Accept': 'application/json'
    }

    try:
    response = requests.get(url, headers=headers, timeout=10)

    if response.status_code == 200:
    data = response.json()
    if data.get('success'):
    return {
    'status': 'encontrado',
    'mensagem': 'CPF localizado com sucesso.',
    'dados': data['data'],
    'acao': 'Prosseguir com o fluxo normal.'
    }
    else:
    return {
    'status': 'nao_encontrado',
    'mensagem': 'CPF não localizado na base de dados.',
    'acao': 'Solicitar verificação ao usuário.'
    }

    elif response.status_code == 400:
    return {
    'status': 'requisicao_invalida',
    'mensagem': 'Formato do CPF inválido na requisição.',
    'acao': 'Verificar formatação do CPF antes de enviar.'
    }

    elif response.status_code == 429:
    return {
    'status': 'rate_limit',
    'mensagem': 'Limite de requisições excedido.',
    'acao': 'Aguardar antes de nova tentativa.'
    }

    elif response.status_code == 401:
    return {
    'status': 'nao_autorizado',
    'mensagem': 'Chave de API inválida ou ausente.',
    'acao': 'Verificar configuração da chave de API.'
    }

    else:
    return {
    'status': 'erro',
    'mensagem': f'Erro HTTP {response.status_code}.',
    'acao': 'Tentar novamente ou acionar suporte.'
    }

    except requests.exceptions.Timeout:
    return {
    'status': 'timeout',
    'mensagem': 'A consulta excedeu o tempo limite.',
    'acao': 'Tentar novamente em alguns segundos.'
    }
    except requests.exceptions.RequestException as e:
    return {
    'status': 'erro_conexao',
    'mensagem': f'Erro de conexão: {str(e)}',
    'acao': 'Verificar conectividade e tentar novamente.'
    }

Códigos HTTP da API e seus significados

A API da CPFHub.io utiliza códigos HTTP padronizados para indicar o resultado de cada requisição:

Casos de uso para consulta de situação cadastral

Abertura de contas bancárias

Instituições financeiras precisam verificar que o CPF está ativo antes de permitir a abertura de conta. CPFs suspensos ou cancelados devem ser rejeitados no onboarding.

Emissão de notas fiscais

A emissão de NF-e com CPF irregular gera rejeição pela Secretaria da Fazenda. Validar o CPF previamente evita retrabalho e atrasos no faturamento.

Concessão de crédito

Análises de crédito devem considerar a situação cadastral do CPF. Um CPF suspenso pode indicar irregularidades que representam risco para o credor.

Contratação de serviços

Plataformas que contratam prestadores de serviço (CLT ou autônomo) precisam verificar o CPF antes de formalizar o vínculo e emitir documentos trabalhistas ou fiscais.

Boas práticas para consulta em escala

• Cache inteligente -- Para CPFs consultados recentemente, utilize um cache local com TTL de 24 horas para evitar consultas desnecessárias.

• Processamento assíncrono -- Para validação em lote, processe as consultas de forma assíncrona, respeitando os rate limits da API.

• Monitoramento -- Acompanhe a taxa de CPFs não encontrados. Um aumento súbito pode indicar problemas na base de dados dos seus clientes.

• Fallback gracioso -- Se a API estiver indisponível, permita que o fluxo continue com validação algorítmica local, agendando a verificação completa para momento posterior.

A CPFHub.io oferece SLA de 99% no plano Pro, reduzindo significativamente a necessidade de ativar o fallback.

Perguntas frequentes

A API da CPFHub.io retorna explicitamente se o CPF é "regular", "suspenso" ou "cancelado"?

A API retorna success: true quando o CPF é localizado com dados cadastrais disponíveis, e success: false quando não é localizado. A ausência de dados pode indicar CPF suspenso, cancelado, nulo ou inexistente. Para saber a situação cadastral exata, o titular precisa consultar diretamente o site da Receita Federal.

Qual é o tempo de resposta da API e como isso afeta a experiência do usuário?

A CPFHub.io responde em aproximadamente 900ms. No contexto de onboarding ou checkout, isso é imperceptível se a consulta for feita de forma assíncrona logo após o usuário avançar na etapa. Implemente um spinner ou indicador de progresso durante a consulta para manter o usuário informado.

É possível consultar CPF em lote para validar uma base de dados existente?

Sim. Implemente um processamento assíncrono que itere sobre a lista respeitando os limites do seu plano. Com o plano Pro (1.000 consultas/mês), é possível validar cerca de 33 CPFs por dia sem custos extras. Para volumes maiores, o plano Corporativo oferece limites personalizados. Armazene os resultados em cache local para evitar reconsultas.

O que significa receber status 400 ou 401 da API de CPF?

Status 400 indica que o CPF foi enviado com formato inválido (diferente de 11 dígitos numéricos). Status 401 indica que a chave de API está ausente, inválida ou expirada. Verifique no dashboard da CPFHub.io se a API key está ativa e se o cabeçalho x-api-key está sendo enviado corretamente na requisição.

Conclusão

Consultar a situação cadastral do CPF via API é uma necessidade operacional para empresas que dependem da validade desse documento para processos de negócio. Automatizar essa verificação elimina a necessidade de consultas manuais, reduz erros e garante que apenas CPFs válidos avancem nos fluxos de onboarding, faturamento e contratação.

Com uma API confiável, tratamento adequado dos diferentes cenários de resposta e boas práticas de integração, sua aplicação estará preparada para lidar com qualquer situação cadastral de forma eficiente e escalável.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e automatize a consulta de CPF no seu fluxo hoje mesmo.