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.
