Integração com API de CPF cpfhub.io

integracao-cpf-api-free-cpfhubio.md

Documentação de Integração: Autopreenchimento Inteligente (CPFHub)

Instrução para IA: Utilize esta especificação lógica para implementar a funcionalidade de "Autopreenchimento de Dados via CPF" em qualquer stack ou linguagem de programação (PHP, Node, Python, React, etc).

---

🎯 Objetivo

Automatizar o preenchimento de formulários de cadastro. Ao digitar o CPF, o sistema deve consultar uma API externa de forma segura e preencher automaticamente os campos Nome e Data de Nascimento.

---

🔐 Arquitetura de Segurança (Obrigatório)

Padrão Proxy (Backend-to-API)

A chave de API (x-api-key) NUNCA deve ser exposta no Frontend (navegador/cliente). A requisição deve seguir estritamente este fluxo:

1. Frontend: Captura o CPF digitado.
2. Frontend: Envia o CPF para o SEU Próprio Backend (endpoint interno).
3. Backend: Autentica a chamada e adiciona a x-api-key (armazenada de forma segura).
4. Backend: Faz a requisição à API Externa (CPFHub).
5. Backend: Retorna os dados limpos para o Frontend.

---

📡 Especificação da API Externa

Endpoint: GET https://api.cpfhub.io/cpf/{cpf}

Parâmetros:

• {cpf}: String numérica (apenas dígitos).

Headers Obrigatórios:

• x-api-key: [SUA_CHAVE_DE_INTEGRACAO]
• Accept: application/json

Resposta de Sucesso (Exemplo Universal):

{
  "success": true,
  "data": {
    "cpf": "12345678900",
    "name": "Nome Completo da Pessoa",
    "birthDate": "15/05/1990",  // Formato: DD/MM/YYYY
    "gender": "M"
  }
}

---

🔄 Algoritmo de Implementação (Lógica)

Siga estes passos lógicos na linguagem de destino:

1. Backend (Servidor)

Crie uma função/rota que aceite um parâmetro cpf.

1. Receba o cpf do cliente.
2. Remova qualquer caractere não numérico.
3. Valide se tem 11 dígitos.
4. Recupere a PRIVATE_KEY das configurações/variáveis de ambiente.
5. Execute uma requisição HTTP GET para a URL da API, injetando a chave no Header.
6. Se a resposta for 200/OK, retorne o JSON data para o cliente.
7. Se falhar, retorne erro tratado.

2. Frontend (Interface)

No formulário de cadastro:

1. Escute o evento de "perda de foco" (blur) ou "conclusão de digitação" no input de CPF.
2. Mostre um indicador visual de "Carregando..." (UX).
3. Chame a sua rota interna do Backend (criada no passo anterior).
4. Ao receber os dados:
   • Preencha o Input Nome com response.name.
   • Preencha o Input Data de Nascimento com response.birthDate.
5. Remova o indicador de carregamento.

---

📋 Mapeamento de Dados (De -> Para)

Dado da API	Destino Sugerido no Formulário	Formato
name	Campo "Nome Completo" ou "Razão Social"	String (Maiúsculas)
birthDate	Campo "Data de Nascimento"	String (dd/mm/aaaa)

---

💡 Informações para Configuração

• A chave de API deve ser armazenada em local seguro (Banco de Dados, .env ou Secrets Manager).
• Não realize a chamada se o CPF for inválido (tamanho != 11).