# Como consumir a API da CPFHub.io em PHP usando cURL > Tutorial passo a passo para consumir a API de consulta de CPF da CPFHub.io em PHP usando cURL. Código completo com tratamento de erros. **Publicado:** 14/05/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/consumir-api-cpfhub-php-curl --- Para consumir a API de CPF da CPFHub.io em PHP com cURL, basta inicializar um handle cURL, configurar a URL do endpoint com o CPF desejado, adicionar o header `x-api-key` com sua chave e executar a requisição. O retorno é um JSON com nome, data de nascimento e gênero do titular em menos de 200ms. A [ANPD](https://www.gov.br/anpd) orienta que dados de identificação pessoal devem ser tratados com finalidade declarada e armazenamento mínimo. ## Introdução O PHP é uma das linguagens mais utilizadas no desenvolvimento web, e o **cURL** é a forma nativa de fazer requisições HTTP em PHP. Se você precisa consultar CPFs via API em um projeto PHP, este tutorial mostra como integrar a API da [**CPFHub.io**](https://www.cpfhub.io/) com código completo, tratamento de erros e boas práticas de segurança. --- ## Pré-requisitos * PHP 7.4+ com extensão cURL habilitada. * Conta gratuita na [CPFHub.io](https://www.cpfhub.io/) para obter sua API key. --- ## Código básico: consulta de CPF ```php "https://api.cpfhub.io/cpf/{$cpf}", CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => [ "x-api-key: {$apiKey}", 'Accept: application/json', ], ]); $response = curl_exec($curl); $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE); $error = curl_error($curl); curl_close($curl); if ($error) { echo "Erro de conexao: {$error}"; exit; } $data = json_decode($response, true); if ($httpCode === 200 && $data['success']) { echo "Nome: " . $data['data']['name'] . "\n"; echo "Nascimento: " . $data['data']['birthDate'] . "\n"; echo "Genero: " . $data['data']['gender'] . "\n"; } else { echo "Erro na consulta. HTTP: {$httpCode}\n"; } ``` --- ## Resposta esperada ```json { "success": true, "data": { "cpf": "12345678900", "name": "João da Silva", "nameUpper": "JOÃO DA SILVA", "gender": "M", "birthDate": "15/06/1990", "day": 15, "month": 6, "year": 1990 } } ``` --- ## Versão com função reutilizável ```php "https://api.cpfhub.io/cpf/{$cpf}", CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => [ "x-api-key: {$apiKey}", 'Accept: application/json', ], ]); $response = curl_exec($curl); $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($httpCode !== 200) { return null; } $data = json_decode($response, true); return $data['success'] ? $data['data'] : null; } // Uso $dados = consultarCpf('123.456.789-00'); if ($dados) { echo "Nome: {$dados['name']}\n"; } else { echo "CPF nao encontrado.\n"; } ``` --- ## Tratamento de erros HTTP ```php 'CPF com formato invalido', 401 => 'Chave de API invalida ou ausente', 404 => 'CPF nao encontrado na base', 500 => 'Erro interno do servidor', default => "Erro desconhecido: HTTP {$httpCode}", }; } ``` --- ## Boas práticas * **Variáveis de ambiente** -- Nunca coloque a chave de API diretamente no código. Use `getenv()` ou arquivos `.env`. * **Timeout** -- Sempre configure `CURLOPT_TIMEOUT` para evitar requisições travadas. * **Sanitização** -- Remova caracteres não numéricos do CPF antes de enviar (`preg_replace('/\D/', '', $cpf)`). * **Cache** -- Para CPFs consultados repetidamente, implemente cache com TTL adequado. * **LGPD** -- Não armazene dados pessoais além do necessário. Mascare CPFs em logs. --- ## Perguntas frequentes ### Como habilitar a extensão cURL no PHP para usar com a API? Verifique se a extensão está ativa rodando `php -m | grep curl`. No Linux/Ubuntu, instale com `sudo apt install php-curl` e reinicie o servidor web. No Windows com XAMPP, descomente `extension=curl` no `php.ini`. Sem a extensão ativa, as funções `curl_init()` e `curl_exec()` não estão disponíveis. ### O que fazer quando a requisição PHP retorna erro de timeout? Configure `CURLOPT_TIMEOUT` com um valor adequado (recomendado: 10 segundos) e `CURLOPT_CONNECTTIMEOUT` com 5 segundos. Se os timeouts persistirem, verifique se o servidor tem saída para a internet na porta 443. Em ambientes com proxy corporativo, configure `CURLOPT_PROXY` com o endereço do proxy. ### Como armazenar a API key com segurança em um projeto PHP? Use variáveis de ambiente lidas com `getenv('CPFHUB_API_KEY')` em vez de hardcodar no código-fonte. Em produção, defina a variável no servidor via painel de controle da hospedagem ou arquivo `.env` carregado pela biblioteca `vlucas/phpdotenv`. Nunca versione arquivos com chaves de API no Git. ### A API CPFHub.io funciona bem com volumes altos de consultas em PHP? Sim. Para consultas em lote, recomenda-se implementar cache para evitar chamadas repetidas do mesmo CPF. O plano gratuito oferece 50 consultas por mês para testes. Ao exceder o limite de qualquer plano, a API não bloqueia — cobra R$0,15 por consulta adicional, sem interrupção do serviço. ### Leia também - [Como consumir APIs REST de CPF em Python usando requests](https://cpfhub.io/blog/como-consumir-apis-rest-de-cpf-em-python-usando-requests) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) --- ## Conclusão Integrar a API da [**CPFHub.io**](https://www.cpfhub.io/) em PHP com cURL é direto: poucos parâmetros de configuração, uma chamada GET e o JSON de resposta já traz nome, data de nascimento e gênero do titular. Com as boas práticas de variáveis de ambiente, timeout e sanitização do CPF, o código fica seguro e pronto para produção. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.