🔐 Painel API

Visão geral

API REST para consulta de dados de pessoa por CPF. Todas as requisições exigem uma API key válida e ativa, e estão sujeitas a rate limiting por minuto e por hora.

Base URL: http://localhost:4500

Formato: JSON  •  Charset: UTF-8

Autenticação

Envie sua API key em uma destas formas (o header x-api-key é o recomendado):

Forma	Exemplo
Header x-api-key	x-api-key: SUA_API_KEY
Header Authorization	Authorization: Bearer SUA_API_KEY
Query string	?apikey=SUA_API_KEY

Sem key, ou com key inválida/desativada → 401 Unauthorized.

GET /api/:cpf

Consulta os dados de uma pessoa pelo CPF.

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
cpf	string	Sim	CPF a consultar (somente números, sem pontos/traços).

Requisição

curl "http://localhost:4500/api/12345678900" \
  -H "x-api-key: SUA_API_KEY"

Resposta 200 — registro encontrado

{
  "success": true,
  "data": {
    "cpf": "12345678900",
    "name": "FULANO DE TAL",
    "birthday": "1990-01-01"
  }
}

Resposta 200 — nenhum registro

{
  "success": false,
  "message": "Nenhum registro encontrado"
}

Erros

// 401 — sem API key
{ "error": "API key ausente. Envie no header x-api-key." }

// 401 — key inválida/desativada
{ "error": "API key inválida ou desativada." }

// 429 — rate limit excedido
{ "error": "Rate limit por minuto excedido. Tente em 42s." }

GET /api/status

Retorna o estado atual do rate limit da sua API key (limites, quanto já usou, quanto resta e quando reseta). Não consome a cota de rate limit — use para checar seu saldo antes de disparar requisições.

Requisição

curl "http://localhost:4500/api/status" \
  -H "x-api-key: SUA_API_KEY"

Resposta 200

{
  "success": true,
  "key": { "name": "Cliente App X", "active": true },
  "rateLimit": {
    "minute": { "limit": 60, "used": 2, "remaining": 58, "resetInSeconds": 35 },
    "hour":   { "limit": 1000, "used": 2, "remaining": 998, "resetInSeconds": 3515 }
  },
  "serverTime": "2026-09-22T09:01:25.555Z"
}

Limite 0 = ilimitado; nesse caso remaining vem como -1.

Rate Limiting

Cada API key tem dois limites, configuráveis no painel (valor 0 = ilimitado):

• Por minuto — janela fixa de 60s.
• Por hora — janela fixa de 60min.

Toda resposta traz os headers de controle:

Header	Descrição
X-RateLimit-Limit-Minute	Limite de requests por minuto (0 = ilimitado).
X-RateLimit-Limit-Hour	Limite de requests por hora (0 = ilimitado).
X-RateLimit-Remaining-Minute	Requests restantes no minuto atual (-1 = ilimitado).
X-RateLimit-Remaining-Hour	Requests restantes na hora atual (-1 = ilimitado).
X-RateLimit-Reset-Minute	Segundos até a janela do minuto reiniciar.
X-RateLimit-Reset-Hour	Segundos até a janela da hora reiniciar.
Retry-After	Segundos até liberar (presente apenas no 429).

Ao exceder o limite → 429 Too Many Requests. Os contadores ficam em memória (cache) e reiniciam junto com o servidor.

Códigos de status

Código	Significado
200	Requisição OK (mesmo quando não há registro, com success:false).
401	API key ausente, inválida ou desativada.
429	Rate limit por minuto ou hora excedido.
500	Erro interno ao consultar o banco.

Exemplos por linguagem

JavaScript (fetch)

const res = await fetch("http://localhost:4500/api/12345678900", {
  headers: { "x-api-key": "SUA_API_KEY" }
});
const data = await res.json();
console.log(data);

Python (requests)

import requests

r = requests.get(
    "http://localhost:4500/api/12345678900",
    headers={"x-api-key": "SUA_API_KEY"},
)
print(r.json())