NovoVerificação de identidade facial

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

Consulte a situação cadastral do CPF na Receita Federal via API em tempo real e entenda as diferenças entre CPF regular, suspenso e cancelado.

Lucas Vieira
Lucas Vieira
··11 min de leitura
Como consultar situação cadastral do CPF via API (regular, suspensa, cancelada)

Para consultar a situação cadastral do CPF via API, use a Consulta em Tempo Real na Receita Federal da CPFHub.io: um POST https://api.cpfhub.io/cpf/realtime com o CPF e a data de nascimento do titular. A resposta traz o campo situation (por exemplo, REGULAR, SUSPENSA ou TITULAR FALECIDO), o ano do óbito em deathYear e links para o comprovante. Cada consulta leva cerca de 1 segundo e custa 1,5 crédito. A Consulta Simples (GET /cpf/{cpf}) não informa situação cadastral: ela retorna nome, gênero e data de nascimento.

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 é uma API que consulta a Receita na hora e devolve a situação em JSON.


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.

Titular falecido

A Receita registrou o óbito do titular. Na Consulta em Tempo Real, esse caso aparece na situation e o ano do óbito vem em deathYear. Um CPF de pessoa falecida usado em cadastro novo é sinal clássico de fraude.


Consultando a situação cadastral via API

A CPFHub.io tem dois produtos de CPF, e só um deles responde a pergunta deste artigo:

ProdutoEndpointO que retornaCusto
Consulta SimplesGET /cpf/{cpf}Nome, gênero e data de nascimento1 crédito por CPF encontrado
Consulta em Tempo RealPOST /cpf/realtimeSituação cadastral, ano do óbito e comprovante1,5 crédito por consulta bem-sucedida

A Consulta em Tempo Real consulta a Receita Federal no momento da chamada. Ela exige o CPF e a data de nascimento do titular (DD/MM/AAAA ou DDMMAAAA):

curl -X POST https://api.cpfhub.io/cpf/realtime \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{"cpf": "12345678909", "birthDate": "15/06/1990"}' \
  --max-time 60

Resposta:

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "FULANO DE TAL",
    "birthDate": "15/06/1990",
    "deathYear": null,
    "situation": "REGULAR",
    "emissionDate": "02/10/2026",
    "emissionTime": "14:32:10",
    "controlCode": "A1B2.C3D4.E5F6.7890",
    "validationUrl": "https://servicos.receita.fazenda.gov.br/...",
    "validationHtmlUrl": "https://api.cpfhub.io/cpf/proof/..."
  }
}

O que cada campo significa:

  • situation -- A situação cadastral como a Receita Federal informa.
  • deathYear -- Ano do óbito como inteiro, ou null. O campo sempre vem na resposta; é null quando não há óbito registrado.
  • validationUrl -- Link de conferência no site da Receita Federal (o mesmo destino do QR code do comprovante). Vem quando a Receita fornece.
  • validationHtmlUrl -- Comprovante guardado pela CPFHub.io, com QR code que leva ao validationUrl. Vem quando o comprovante é gerado com sucesso.
  • emissionDate, emissionTime, controlCode -- Dados de emissão do comprovante, quando a Receita fornece.

A consulta leva cerca de 1 segundo (tempo típico, não é SLA) e é feita CPF a CPF: não existe versão em lote. Só a resposta 200 consome crédito. A referência completa está na documentação da Consulta em Tempo Real.


Como tratar cada cenário na aplicação

CPF regular

Com situation igual a REGULAR e deathYear nulo, a aplicação pode seguir o fluxo normal. Guarde o validationHtmlUrl se precisar de evidência para auditoria.

Situação diferente de regular

Suspensa, pendente de regularização, cancelada ou nula: o tratamento depende da política da empresa. Em abertura de conta e concessão de crédito, o comum é recusar ou mandar para análise manual. Em cadastros de menor risco, dá para seguir e pedir que o titular regularize o CPF.

Óbito registrado

Se deathYear vier preenchido ou a situação indicar titular falecido, trate como tentativa de fraude até prova em contrário.

Consulta recusada pela Receita (422)

O 422 aparece quando o dígito verificador está errado ou quando a Receita recusa a consulta, por exemplo porque a data de nascimento não confere. Nesse caso:

  • Solicitar verificação ao usuário -- Peça que o usuário confira o CPF e a data de nascimento.
  • 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. Muitas recusas seguidas do mesmo usuário merecem atenção.

Implementação de tratamento de respostas

import requests

URL = "https://api.cpfhub.io/cpf/realtime"

def consultar_situacao(cpf: str, nascimento: str, api_key: str) -> dict:
    """Consulta a situação cadastral do CPF na Receita Federal."""
    cpf_limpo = "".join(filter(str.isdigit, cpf))
    if len(cpf_limpo) != 11:
        return {"status": "formato_invalido", "acao": "Solicitar novo CPF ao usuário."}

    try:
        resp = requests.post(
            URL,
            headers={"x-api-key": api_key},
            json={"cpf": cpf_limpo, "birthDate": nascimento},  # DD/MM/AAAA
            timeout=60,  # a Receita pode demorar; use pelo menos 60 s
        )
    except requests.exceptions.Timeout:
        # Não repita sozinho: o POST não é idempotente e a consulta pode ter sido cobrada
        return {"status": "timeout", "acao": "Conferir o consumo antes de tentar de novo."}

    if resp.status_code == 200:
        dados = resp.json()["data"]
        if dados["deathYear"] is not None or dados["situation"] == "TITULAR FALECIDO":
            acao = "Recusar: há óbito registrado."
        elif dados["situation"] == "REGULAR":
            acao = "Prosseguir com o fluxo normal."
        else:
            acao = "Encaminhar para análise conforme a política da empresa."
        return {
            "status": dados["situation"],
            "ano_obito": dados["deathYear"],
            "comprovante": dados.get("validationHtmlUrl"),
            "acao": acao,
        }

    if resp.status_code == 422:
        return {"status": "recusado", "acao": "Pedir que o usuário confira CPF e data de nascimento."}
    if resp.status_code == 429:
        espera = resp.headers.get("Retry-After")
        return {"status": "rate_limit", "acao": f"Aguardar {espera} s e tentar de novo."}
    if resp.status_code in (502, 503):
        return {"status": "receita_indisponivel", "acao": "Tentar de novo em alguns segundos."}
    if resp.status_code == 401:
        return {"status": "nao_autorizado", "acao": "Verificar a chave de API."}
    if resp.status_code == 403:
        return {"status": "sem_credito_ou_conta_bloqueada", "acao": "Verificar saldo e conta no painel."}
    return {"status": "erro", "acao": f"HTTP {resp.status_code}: revisar a requisição."}

Códigos HTTP da Consulta em Tempo Real

A API da CPFHub.io usa o status HTTP para indicar o resultado. Decida pelo status, nunca pelo texto da mensagem:

CódigoSignificadoAção recomendada
200Consulta concluídaLer situation e deathYear
400CPF sem 11 dígitos ou data de nascimento inválidaCorrigir o formato antes de enviar
401API Key ausente, inválida ou inativaVerificar a chave no dashboard
403Créditos esgotados (em plano sem excedente) ou conta inativa/bloqueadaVerificar saldo e plano
422Dígito verificador incorreto ou consulta recusada pela Receita (por exemplo, data de nascimento divergente)Pedir que o usuário confira os dados
429Limite por minuto excedido (padrão de 5 por minuto nesta consulta)Esperar o tempo do header Retry-After
502A Receita Federal não respondeu a tempoTentar de novo em alguns segundos (sem cobrança)
503Receita com alta demanda ou saldo indisponível no momentoTentar de novo em alguns segundos (sem cobrança)

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.

  • Fila com ritmo controlado -- A Consulta em Tempo Real não tem versão em lote e o limite padrão é de 5 consultas por minuto. Para revalidar uma base, use uma fila que respeite esse ritmo e o header Retry-After.

  • Monitoramento -- Acompanhe a taxa de respostas 422. Um aumento súbito pode indicar datas de nascimento erradas na sua base ou tentativas de fraude.

  • 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 e de 99,9% no Corporativo. Lembre que, na Consulta em Tempo Real, a disponibilidade também depende da Receita Federal: os erros 502 e 503 não são cobrados.


Perguntas frequentes

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

Sim, pela Consulta em Tempo Real. O POST /cpf/realtime devolve o campo situation com a situação como a Receita Federal informa, além de deathYear. A Consulta Simples (GET /cpf/{cpf}) não traz essa informação, e um 404 nela significa apenas que o CPF não está na base da CPFHub.io, não que ele esteja irregular.

Quanto custa consultar a situação cadastral?

1,5 crédito por consulta bem-sucedida. Respostas de erro, incluindo 502 e 503 quando a Receita não responde, não consomem crédito. O plano Grátis tem 50 créditos por mês, sem cartão, o que dá para cerca de 33 consultas em tempo real. Os planos pagos estão na página de preços.

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

A Consulta em Tempo Real leva cerca de 1 segundo, porque consulta a Receita na hora. A Consulta Simples responde em cerca de 150 ms. Nenhum dos dois é SLA. No onboarding, faça a consulta logo depois que o usuário informa CPF e data de nascimento e mostre um indicador de progresso. Configure timeout de pelo menos 60 segundos no cliente.

O comprovante da consulta serve como evidência?

A resposta traz o validationUrl, link de conferência no site da Receita, quando a Receita fornece, e o validationHtmlUrl, comprovante guardado pela CPFHub.io com QR code que leva a esse link. Guarde os dois junto ao registro do cliente.

É possível consultar a situação cadastral em lote?

Não. A Consulta em Tempo Real é feita CPF a CPF, com limite padrão de 5 por minuto. O lote da CPFHub.io (POST /cpf/bulk, até 10.000 CPFs) usa a Consulta Simples e retorna nome, gênero e data de nascimento, sem situação cadastral. Para planos com limites diferentes, fale com o suporte em suporte@cpfhub.io.

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) ou, na Consulta em Tempo Real, que a data de nascimento está em formato inválido. 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 consulta manual e impede que CPFs suspensos, cancelados ou de pessoas falecidas avancem nos fluxos de onboarding, faturamento e contratação.

O caminho é a Consulta em Tempo Real: CPF e data de nascimento na entrada, situação cadastral, ano do óbito e comprovante na saída. Trate o 422 como pedido de conferência ao usuário, respeite o Retry-After e não repita chamadas depois de um timeout local.

Veja os detalhes da Consulta em Tempo Real na Receita Federal e crie sua conta em app.cpfhub.io: o plano Grátis tem 50 créditos por mês, sem cartão, e já permite testar a consulta.

CPFHub.io

Pronto para integrar a API?

50 créditos gratuitos para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

WhatsApp