Como consultar CPF via API usando Postman e cURL

Consultar CPF via API usando Postman e cURL é o caminho mais rápido para testar e validar a integração antes de implementá-la em produção. Com a API da CPFHub.io, você faz uma requisição GET simples com o header x-api-key e recebe nome, gênero e data de nascimento do titular em aproximadamente 900ms — sem configuração complexa, sem cartão de crédito para começar.

Introdução

A consulta de CPF via API é um processo essencial para empresas que precisam validar identidades de forma rápida e segura. Ferramentas como Postman e cURL são ideais para testar e integrar APIs antes de implementá-las em produção. A API da CPFHub.io oferece um endpoint simples e bem documentado que você pode testar em minutos com qualquer uma dessas ferramentas.

1. O que é o Postman e o cURL?

Postman

O Postman é uma plataforma popular para desenvolvimento e testes de APIs. Ele permite enviar requisições HTTP, visualizar respostas e depurar problemas com facilidade.

Vantagens:

• Interface gráfica intuitiva.
• Suporte a diferentes métodos HTTP (GET, POST, PUT, DELETE, etc.).
• Permite salvar e compartilhar coleções de requisições.

cURL

O cURL é uma ferramenta de linha de comando que permite fazer requisições HTTP diretamente do terminal.

Vantagens:

• Simples e rápido para testar APIs.
• Funciona em qualquer sistema operacional.
• Facilmente integrável com scripts automatizados.

2. Configuração inicial da API

Antes de realizar consultas, é necessário:

1. Obter uma chave de API (API Key) no provedor da API.
2. Configurar os headers corretamente.
3. Montar a requisição no formato adequado.

A CPFHub.io disponibiliza uma API key gratuita imediatamente após o cadastro, sem necessidade de cartão de crédito, permitindo até 50 consultas por mês para testes e projetos iniciais.

3. Como consultar um CPF via API no Postman

Passo 1: Criar uma nova requisição

1. Abra o Postman.
2. Clique em New Request.
3. Selecione o método GET.
4. No campo URL, insira: https://api.cpfhub.io/cpf/12345678900

Passo 2: Adicionar os headers

Vá até a aba Headers e adicione:

Passo 3: Enviar a requisição

Clique em Send e verifique a resposta retornada pela API. Note que o CPF é enviado diretamente na URL, sem necessidade de corpo na requisição.

4. Como consultar um CPF via API usando cURL

Se preferir usar a linha de comando, execute o seguinte comando cURL:

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json"

Se a API estiver configurada corretamente, você receberá uma resposta como esta:

{
    "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
    }
}

Se a resposta indicar sucesso, significa que a API está funcionando corretamente.

5. Dicas para resolver erros comuns

Erro 401 - Unauthorized

Causa: Chave de API inválida ou ausente.

Solução: Verifique se x-api-key está correto e ativo.

Erro 400 - Bad Request

Causa: Formato do CPF incorreto na URL.

Solução: Confirme se o CPF está no formato correto (apenas números, 11 dígitos).

Erro 500 - Internal Server Error

Causa: Problema no servidor da API.

Solução: Aguarde e tente novamente ou entre em contato com o suporte da API.

Perguntas frequentes

Como obter a chave de API da CPFHub.io para usar no Postman ou cURL?

Acesse cpfhub.io, crie uma conta gratuita e acesse o painel. A API key é gerada automaticamente e fica disponível em app.cpfhub.io/settings/billing. Copie a chave e use-a no header x-api-key de todas as requisições. O plano gratuito permite 50 consultas mensais sem cartão de crédito.

A API CPFHub.io retorna erro quando o limite de consultas é atingido?

Não. Diferente de muitas APIs, a CPFHub.io não retorna HTTP 429 nem bloqueia as requisições ao atingir o limite do plano. O plano gratuito oferece 50 consultas mensais e, ao ultrapassar esse limite, cobra R$0,15 por consulta adicional automaticamente — sem interromper o serviço. O plano Pro inclui 1.000 consultas por R$149/mês com o mesmo modelo de excedente.

Como garantir conformidade com a LGPD ao testar a API com Postman ou cURL?

Nos testes, use CPFs fictícios gerados por ferramentas de desenvolvimento, nunca CPFs reais de pessoas sem autorização. Em produção, documente a finalidade do tratamento, armazene apenas o necessário e consulte as diretrizes da ANPD para garantir que o uso da API está dentro de uma base legal adequada.

Posso automatizar consultas em lote usando cURL num script shell?

Sim. Você pode criar um script shell que lê uma lista de CPFs de um arquivo e faz chamadas sequenciais à API com cURL. Recomenda-se adicionar um intervalo de 1 segundo entre chamadas para evitar sobrecarga e usar --max-time 10 para definir timeout. Lembre-se de armazenar a API key em variável de ambiente (export API_KEY=...) e nunca hardcoded no script.

Conclusão

Usar Postman e cURL para consultar um CPF via API é uma maneira rápida e prática de testar e integrar essa funcionalidade ao seu sistema. A API retorna dados como nome completo, nome em maiúsculas, gênero e data de nascimento (com dia, mês e ano separados), com tempo de resposta de aproximadamente 900ms.

A CPFHub.io oferece documentação completa, exemplos prontos para Postman e cURL, e um plano gratuito para você começar sem burocracia.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.