Como consultar a situação do CPF na Receita Federal com PHP e a APIBrasil

Conferir se um CPF existe e está regular na Receita Federal é o primeiro filtro contra fraude em cadastros, vendas a prazo, aberturas de conta e contratações. Neste tutorial você vai aprender a consultar a situação do CPF na Receita Federal com PHP usando a API CPF – Receita Federal da APIBrasil, com código pronto para colocar no seu projeto.

Também vamos falar do que muita gente esquece: o CPF é dado pessoal, e a consulta precisa respeitar a LGPD.

O que a API CPF – Receita Federal devolve

A API fica na categoria Análise Antifraude do catálogo e custa R$ 0,34 por consulta em produção. Com o número do CPF, ela devolve:

Campo	Descrição
`nome`	Nome completo cadastrado na Receita
`data_nascimento`	Data de nascimento
`situacao_receita`	Situação cadastral do CPF (por exemplo, regular)
`situacao_receita_data`	Data da última atualização da situação
`mae`, `sexo`, `idade`	Dados complementares do cadastro
`protocolo`	Protocolo da consulta, útil para auditoria

Os dados ficam dentro de data.content.nome.conteudo, e o campo existe_informacao indica se o CPF foi encontrado.

Pré-requisitos

PHP 8.0 ou mais novo, com a extensão cURL habilitada (confira com php -m | grep curl).
Seu Bearer Token da APIBrasil, em Credenciais no painel. Veja os primeiros passos na APIBrasil se ainda não tem.

Passo 1: a chamada

POST https://gateway.apibrasil.io/api/v2/consulta/cpf/credits
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "tipo": "receita-federal",
  "cpf": "00000000000",
  "homolog": true
}

O CPF vai só com números, sem pontos nem hífen. Com homolog: true a consulta não é tarifada, o que permite desenvolver e testar à vontade.

Passo 2: valide o CPF antes de consultar

Cada consulta em produção custa dinheiro. Por isso vale conferir os dígitos verificadores localmente antes de chamar a API: um CPF digitado errado nem chega ao gateway.

<?php
function cpfValido(string $cpf): bool
{
    $cpf = preg_replace('/\D/', '', $cpf);
    if (strlen($cpf) !== 11 || preg_match('/^(\d)\1{10}$/', $cpf)) {
        return false;
    }
    for ($t = 9; $t < 11; $t++) {
        $soma = 0;
        for ($i = 0; $i < $t; $i++) {
            $soma += (int) $cpf[$i] * (($t + 1) - $i);
        }
        $digito = ((10 * $soma) % 11) % 10;
        if ((int) $cpf[$t] !== $digito) {
            return false;
        }
    }
    return true;
}

Passo 3: o cliente em PHP

Crie o arquivo consulta_cpf.php. O token vem de variável de ambiente, nunca escrito no código:

<?php
require __DIR__ . '/cpf_valido.php';

const URL = 'https://gateway.apibrasil.io/api/v2/consulta/cpf/credits';

function consultarCpf(string $cpf): array
{
    $cpf = preg_replace('/\D/', '', $cpf);
    if (!cpfValido($cpf)) {
        throw new InvalidArgumentException('CPF inválido');
    }

    $corpo = json_encode([
        'tipo'    => 'receita-federal',
        'cpf'     => $cpf,
        'homolog' => getenv('APIBRASIL_HOMOLOG') !== 'false',
    ]);

    $ch = curl_init(URL);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $corpo,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 120,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'Authorization: Bearer ' . getenv('APIBRASIL_TOKEN'),
        ],
    ]);

    $resposta = curl_exec($ch);
    $status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $erroCurl = curl_error($ch);
    curl_close($ch);

    if ($resposta === false) {
        throw new RuntimeException('Falha de conexão: ' . $erroCurl);
    }
    if ($status === 402) {
        throw new RuntimeException('Saldo insuficiente na APIBrasil. Recarregue a conta.');
    }
    if ($status >= 400) {
        throw new RuntimeException("HTTP $status: " . substr($resposta, 0, 200));
    }

    $json = json_decode($resposta, true);
    // Mesmo com HTTP 200, o erro pode vir no corpo.
    if (!empty($json['error'])) {
        throw new RuntimeException($json['message'] ?? 'Erro na consulta');
    }
    return $json;
}

$r = consultarCpf($argv[1] ?? '');
$pessoa = $r['data']['content']['nome']['conteudo'] ?? null;

if (!$pessoa) {
    echo "CPF não encontrado na base consultada\n";
    exit(1);
}

echo 'Nome ............. ' . $pessoa['nome'] . PHP_EOL;
echo 'Nascimento ....... ' . $pessoa['data_nascimento'] . PHP_EOL;
echo 'Situação ......... ' . $pessoa['situacao_receita'] . PHP_EOL;
echo 'Atualizado em .... ' . $pessoa['situacao_receita_data'] . PHP_EOL;
echo 'Custo ............ R$ ' . $r['tax'] . PHP_EOL;

Passo 4: rode e confira o resultado

export APIBRASIL_TOKEN="seu_token_aqui"
export APIBRASIL_HOMOLOG=true
php consulta_cpf.php 123.456.789-09

Terminal executando script PHP que consulta a situação do CPF na Receita Federal — Resultado da consulta em homologação: situação cadastral e data da última atualização.

A estrutura que o código lê fica assim (dados fictícios):

Estrutura JSON da resposta da API CPF Receita Federal da APIBrasil — Os dados da pessoa ficam em <code>data.content.nome.conteudo</code>. Dados fictícios.

Como usar o resultado no seu cadastro

Uma regra simples e eficiente para cadastros:

CPF com dígitos inválidos: recusa na hora, sem chamar a API.
Situação regular: segue o fluxo normal.
Qualquer outra situação (suspensa, cancelada, pendente de regularização, titular falecido): manda para análise manual.
Nome diferente do informado pelo cliente: também vai para análise.

Comparar o nome digitado com o nome da Receita pega boa parte das fraudes de identidade. Normalize os dois (maiúsculas, sem acento) antes de comparar.

CPF e LGPD: o que você precisa observar

Consultar CPF é tratamento de dado pessoal. Alguns cuidados básicos:

Tenha uma base legal, como execução de contrato, prevenção à fraude ou cumprimento de obrigação legal, e registre essa justificativa.
Consulte só o necessário: se você só precisa da situação cadastral, não guarde nome da mãe e data de nascimento.
Proteja o log: não grave a resposta completa em logs abertos. Mascare o CPF (123.*.*-09).
Informe o titular na sua política de privacidade que a verificação é feita.

Este tutorial é técnico e não substitui orientação jurídica. Para o seu caso concreto, converse com o encarregado de dados (DPO) da sua empresa.

Perguntas frequentes

Qual a diferença para as outras APIs de CPF do catálogo?

A APIBrasil tem várias APIs de CPF, de consultas simples a relatórios completos de compliance. A CPF – Receita Federal é a indicada para validar a situação cadastral. Se você precisa de score, restrições ou dados de compliance, veja as opções nas categorias Análise de Crédito e Análise Antifraude em doc.apibrasil.io.

Posso usar em Laravel?

Sim. Coloque a função consultarCpf em um Service e leia o token com env('APIBRASIL_TOKEN') pela configuração. Se está começando no framework, veja o tutorial de Laravel.