# CPFHub.io

> API de consulta de CPF brasileiro. Retorna nome completo, gênero e data de nascimento a partir de um número de CPF.

## Conteúdo para LLMs

- Referência completa desta API (este arquivo): https://cpfhub.io/llms.txt
- Conteúdo completo + índice do blog: https://cpfhub.io/llms-full.txt
- Sitemap (todos os URLs publicados): https://cpfhub.io/sitemap.xml
- Blog técnico (1000+ artigos sobre CPF, KYC, LGPD): https://cpfhub.io/blog
- Qualquer artigo em markdown limpo: https://cpfhub.io/blog/[slug].md
- Qualquer página de documentação em markdown limpo: https://cpfhub.io/documentacao/[caminho].md (ex: https://cpfhub.io/documentacao/quickstart/nodejs.md)

CPFHub.io fornece uma REST API simples para verificar identidade de pessoas físicas brasileiras usando o CPF (Cadastro de Pessoas Físicas). A API é usada em fluxos de KYC, onboarding, prevenção de fraudes e preenchimento automático de formulários.

## Endpoints

- Base URL: https://api.cpfhub.io
- Autenticação: header `x-api-key`
- Formato: JSON

### GET /v1/cpf/{cpf}

Consulta um CPF e retorna os dados de identidade.

**Parâmetros:**
- `cpf` (path, obrigatório): CPF com ou sem formatação

**Resposta 200:**
```json
{
  "success": true,
  "data": {
    "cpf": "123.456.789-09",
    "name": "Fulano de Tal",
    "nameUpper": "FULANO DE TAL",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}
```

**Códigos de erro:**
- `400 INVALID_CPF_FORMAT` — formato inválido
- `401 INVALID_API_KEY` — chave ausente ou inválida
- `403 INSUFFICIENT_CREDITS` — sem créditos
- `404 CPF_NOT_FOUND` — CPF não encontrado (não consome crédito)
- `422 INVALID_CPF_DIGITS` — dígitos verificadores inválidos
- `429 RATE_LIMIT_EXCEEDED` — rate limit excedido, use Retry-After header

### GET /quota

Retorna o saldo de créditos disponível e o status do plano da conta. Somente leitura, nunca consome crédito, e funciona mesmo com o saldo de créditos esgotado.

**Resposta 200:**
```json
{
  "success": true,
  "data": {
    "plan": "Customizado",
    "remainingCredits": 49,
    "billingStatus": "active",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "usuario@exemplo.com"
  }
}
```

**Códigos de erro:**
- `401` — API Key ausente ou inválida (`{"success":false,"error":"API Key inválida"}`)
- `403` — conta de usuário inativa (não ocorre por falta de créditos)
- `500` — erro interno ao validar assinatura

## Documentação completa

- Início Rápido: https://cpfhub.io/documentacao/inicio
- Referência da API: https://cpfhub.io/documentacao/referencia/cpf
- Saldo de créditos: https://cpfhub.io/documentacao/referencia/quota
- Códigos de erro: https://cpfhub.io/documentacao/referencia/codigos
- OpenAPI spec (JSON): https://cpfhub.io/openapi.json
- OpenAPI spec (YAML): https://cpfhub.io/openapi.yaml
- MCP Server: https://cpfhub.io/documentacao/ai/mcp
- Agent Skills: https://cpfhub.io/documentacao/ai/skills
- Biblioteca de Prompts: https://cpfhub.io/documentacao/ai/prompts

## SDKs Oficiais

Node.js/TypeScript: npm install @cpfhub/sdk
Python: pip install cpfhub
Go: go get github.com/cpfhub/cpfhub-go
PHP: composer require cpfhub/cpfhub-php
Java: io.cpfhub:cpfhub-java (Maven/Gradle)
Ruby: gem install cpfhub
Rust: cargo add cpfhub
.NET: dotnet add package CPFHub.SDK
Dart/Flutter: dart pub add cpfhub
Swift: SPM github.com/cpfhub/cpfhub-swift
Elixir: hex cpfhub
Lua: luarocks install cpfhub
Nim: nimble install cpfhub

## Para AI Agents

### Tool definition (OpenAI function calling)

```json
{
  "name": "get_person_by_cpf",
  "description": "Consulta dados de identidade de uma pessoa a partir do CPF. Retorna nome, gênero e data de nascimento. Retorna erro se o CPF não for encontrado.",
  "parameters": {
    "type": "object",
    "properties": {
      "cpf": {
        "type": "string",
        "description": "CPF com ou sem formatação (ex: 12345678909 ou 123.456.789-09)"
      }
    },
    "required": ["cpf"]
  }
}
```

### Exemplo de uso em Python

```python
from cpfhub import CPFHub
client = CPFHub(api_key="sua-api-key")
result = client.lookup("12345678909")
print(result.data.name)  # "Fulano de Tal"
```

### Exemplo de uso em Node.js

```javascript
import { CPFHub } from '@cpfhub/sdk'
const client = new CPFHub({ apiKey: process.env.CPFHUB_API_KEY })
const result = await client.lookup('12345678909')
console.log(result.data.name) // "Fulano de Tal"
```

### MCP Server

Para usar com Claude Desktop, Cursor e outros clientes MCP:
```json
{
  "mcpServers": {
    "cpfhub": {
      "command": "npx",
      "args": ["-y", "@cpfhub/mcp-server"],
      "env": { "CPFHUB_API_KEY": "sua-api-key" }
    }
  }
}
```

## Compliance e LGPD

A API opera sob base legal do Art. 7º, II e IX da LGPD (legítimo interesse e execução de contrato). Os dados retornados são de registro público. Nenhum dado sensível (saúde, biometria, financeiro) é fornecido. Dados não são armazenados após a resposta.

Contato DPO: dpo@cpfhub.io
Política de privacidade: https://cpfhub.io/privacidade