# 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. Produto live: consulta individual (GET) e consulta em lote (POST bulk).

## Somos / Não somos

**Somos**
- REST API para consulta de dados cadastrais vinculados a CPF (nome, gênero, data de nascimento).
- Consulta síncrona (`GET /cpf/{cpf}`) e consulta em lote assíncrona (`POST /cpf/bulk`, até 10.000 CPFs).
- Autenticação por API Key (`x-api-key`). Planos em créditos mensais.

**Não somos**
- Não oferecemos, como produto live, KYC com biometria, selfie, OCR de documento ou face match.
- Não retornamos situação cadastral na Receita Federal nem fazemos consulta live no site da Receita.
- Não publicamos número de latência neste arquivo — use medições internas ou a página de status.

## Conteúdo para LLMs

- Referência rápida da API (este arquivo): https://cpfhub.io/llms.txt
- Índice ampliado (blog + resumo): https://cpfhub.io/llms-full.txt
- OpenAPI (JSON): https://cpfhub.io/openapi.json
- OpenAPI (YAML): https://cpfhub.io/openapi.yaml
- Sitemap: https://cpfhub.io/sitemap.xml
- Blog em markdown limpo: https://cpfhub.io/blog/[slug].md
- Preços (fonte de planos/SLA): https://www.cpfhub.io/precos
- Status: https://app.cpfhub.io/status
- Documentação: https://cpfhub.io/documentacao/inicio

Nota: páginas de documentação em `.md` ainda não estão disponíveis de forma confiável; use as URLs HTML da docs ou o OpenAPI.

## Endpoints

- Base URL: `https://api.cpfhub.io`
- Autenticação: header `x-api-key`
- Formato: JSON
- Versão: v1 implícita (**não** faz parte da URL)

### GET /cpf/{cpf}

Consulta um CPF e retorna os dados cadastrais.

**Parâmetros:**
- `cpf` (path, obrigatório): CPF com ou sem formatação na **entrada**
- Resposta: `data.cpf` sempre **11 dígitos sem máscara** (ex.: `12345678909`)

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

**Cobrança:** apenas HTTP 200 com `success: true` consome 1 crédito. `404` / `400` / `422` **não** consomem crédito.

**Códigos de erro (resumo):**
- `400` — formato inválido (`INVALID_CPF_FORMAT`)
- `401` — API Key ausente ou inválida (`error` como string)
- `403` — chave suspensa; ou créditos esgotados **sem overage** (Grátis / pago com overage off): body `{"success":false,"error":"Limite de créditos excedido"}`. Planos **com overage ativo** não dão 403 de crédito — excedente no ciclo seguinte
- `404 CPF_NOT_FOUND` — não encontrado (não consome crédito)
- `422 INVALID_CPF_DIGITS` — dígitos verificadores inválidos
- `429 RATE_LIMIT_EXCEEDED` — use header `Retry-After`

### POST /cpf/bulk

Enfileira até **10.000** CPFs para processamento assíncrono. Retorna `202` com `jobId`.

```http
POST https://api.cpfhub.io/cpf/bulk
Content-Type: application/json
x-api-key: SUA_API_KEY

{ "cpfs": ["10415045606", "11144477735"] }
```

Consulte o status em `GET /cpf/bulk/{jobId}` até `data.status` ser `done` ou `failed`.
Apenas itens com `found: true` consomem crédito. Itens sem crédito podem aparecer como `skipped`.

Docs: https://cpfhub.io/documentacao/referencia/lote

### GET /quota

Saldo de créditos e plano. Somente leitura; **nunca** consome crédito; funciona com saldo zero.

Docs: https://cpfhub.io/documentacao/referencia/quota

## Planos e cobrança (fonte: /precos)

| Plano | Preço | Créditos/mês | SLA (card) |
|---|---|---|---|
| Grátis | R$ 0 | 50 · sem cartão | 95% |
| Pro | tile padrão R$ 149 / 1.000 cr (também 100 / 5.000 / 10.000) | excedente R$ 0,15/cr no ciclo seguinte | 99% |
| Corporativo | sob consulta | >10.000 | 99,9% |

- Créditos não utilizados **não acumulam**.
- **Grátis** (sem overage): em 0 créditos **bloqueia** — GET 403 `"Limite de créditos excedido"`; lote `skipped`. Sem overage.
- Planos **com overage ativo** (ex. Pro): ao zerar a franquia, continua; excedente no ciclo seguinte. Sem 403 de crédito por franquia.
- Pago com overage desligado: mesmo bloqueio do Grátis.
- Não diga "API nunca bloqueia".

## Rate limits

| Plano | Limite |
|---|---|
| Grátis | 1 requisição a cada 2 segundos |
| Pro | 1 requisição por segundo |
| Corporativo | sob consulta |

## Documentação completa

- Introdução: https://cpfhub.io/documentacao/introducao
- Consulta CPF: https://cpfhub.io/documentacao/referencia/cpf
- Lote: https://cpfhub.io/documentacao/referencia/lote
- Quota: https://cpfhub.io/documentacao/referencia/quota
- Códigos de erro: https://cpfhub.io/documentacao/referencia/codigos
- FAQ: https://cpfhub.io/documentacao/faq
- MCP Server: https://cpfhub.io/documentacao/ai/mcp
- Agent Skills: https://cpfhub.io/documentacao/ai/skills

## 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`
Ruby: `gem install cpfhub`
Rust: `cargo add cpfhub`
.NET: `dotnet add package CPFHub.SDK`
Dart: `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 cadastrais de uma pessoa a partir do CPF. Retorna nome, gênero e data de nascimento. Erro se o CPF não for encontrado. Não realiza biometria nem consulta situação na Receita Federal.",
  "parameters": {
    "type": "object",
    "properties": {
      "cpf": {
        "type": "string",
        "description": "CPF com ou sem formatação (ex: 12345678909 ou 123.456.789-09)"
      }
    },
    "required": ["cpf"]
  }
}
```

### Exemplo Python

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

### Exemplo 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)
```

### MCP Server

```json
{
  "mcpServers": {
    "cpfhub": {
      "command": "npx",
      "args": ["-y", "@cpfhub/mcp-server"],
      "env": { "CPFHUB_API_KEY": "sua-api-key" }
    }
  }
}
```

## Compliance e LGPD

A API retorna nome, gênero e data de nascimento. Não retorna dados sensíveis de saúde, biometria ou financeiro nesta API.

- Privacidade: https://cpfhub.io/privacidade
- Suporte: suporte@cpfhub.io
- DPO: dpo@cpfhub.io
- App / registro: https://app.cpfhub.io