Tutorial

Como integrar uma API de CPF em PHP: guia com cURL

Integre a API de CPF em PHP com cURL, API Key, timeout, tratamento de erros HTTP e leitura segura do JSON.

Imagem editorial sobre PHP com cURL e JSON
PHP com cURL e JSON.

O que é necessário para integrar CPF em PHP

Para usar uma API de CPF em PHP, você precisa de PHP com extensão cURL, uma API Key criada no painel e um fluxo legítimo que justifique a consulta. O endpoint documentado é GET https://api.apicpf.dev/consulta?cpf= com X-API-KEY. A consulta consome um crédito; a validação matemática, em /v1/validate, não consome créditos de consulta. Consulte a documentação oficial.

A API Key deve existir somente no backend. O formulário do usuário chama seu servidor; ele consulta o serviço e devolve apenas os campos realmente necessários.

Exemplo de PHP com cURL, timeout e tratamento de erros

<?php
function consultarCpf(string $cpf): array {
    $cpf = preg_replace('/\D/', '', $cpf);
    if (strlen($cpf) !== 11) {
        throw new InvalidArgumentException('CPF deve ter 11 dígitos');
    }
    $key = getenv('APICPF_KEY');
    if (!$key) throw new RuntimeException('API Key não configurada');

    $url = 'https://api.apicpf.dev/consulta?cpf=' . rawurlencode($cpf);
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 3,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => [
            'X-API-KEY: ' . $key,
            'Accept: application/json',
        ],
    ]);
    $response = curl_exec($ch);
    $error = curl_error($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($response === false) throw new RuntimeException('Falha de rede: ' . $error);
    $json = json_decode($response, true);
    if (!is_array($json)) throw new RuntimeException('JSON inválido');
    if ($status !== 200) throw new RuntimeException('Falha HTTP: ' . $status);
    return $json;
}

// CPF de exemplo da documentação pública.
$result = consultarCpf('52998224725');
$nome = $result['data']['nome'] ?? null;

O exemplo ilustra uma integração HTTP, não um sistema completo de autorização, identificação ou cobrança. Não execute consultas de CPF sem finalidade adequada. Não registre a URL com CPF, a chave ou a resposta integral em ferramentas de log.

Como ler o JSON da consulta

O contrato apresenta code e um objeto data com cpf, nome, mae, genero e data_nascimento. Acesse cada chave verificando sua existência e não considere uma resposta cadastral prova de identidade.

{
  "code": 200,
  "data": {
    "cpf": "52998224725",
    "nome": "Maria Aparecida da Silva",
    "mae": "Ana da Silva",
    "genero": "F",
    "data_nascimento": "1988-03-12"
  }
}

Dados fictícios de demonstração usados pela documentação.

Quais erros podem acontecer?

  • 400: CPF com formato inválido; revise entrada e validação.
  • 401: chave ausente ou inválida; verifique variável de ambiente e header.
  • 402: sem créditos; revise saldo antes de tentar novamente.
  • 403: conta bloqueada ou IP fora da allowlist.
  • 404: revise endpoint e mensagem; não assuma que todo 404 indica CPF inexistente.
  • 429: limite de taxa; use fila e espera progressiva.
  • 500 e timeout: trate a indisponibilidade de forma controlada.

Veja como tratar erros 401, 402, 404 e 429.

Validação antes da consulta

Use /v1/validate?cpf= para verificar formato e dígitos antes de consumir um crédito com /consulta. Um CPF matematicamente válido não comprova que o número está ativo ou pertence ao usuário. Restrinja consultas ao contexto necessário e evite persistir dados retornados por padrão.

Perguntas frequentes

Posso colocar a API Key no JavaScript?

Não. Isso a expõe para qualquer pessoa que abra as ferramentas do navegador.

A consulta via API é POST?

O endpoint documentado é GET. Você pode usar POST apenas entre o frontend e seu próprio backend, que fará a chamada GET com a chave protegida.

Continue aprendendo