Documentação da API

Autenticação

Toda chamada precisa do header Authorization: Bearer cap_live_…. Você gera a chave no painel da empresa em /empresa/api. O hash SHA-256 da chave é o que guardamos no banco — você só vê o texto puro uma vez.

# Header padrão
Authorization: Bearer cap_live_a1b2c3d4e5f6g7h8...

# Alternativa
x-api-key: cap_live_a1b2c3d4e5f6g7h8...

Base URL

https://suacapivara.com.br/api/v1

Toda resposta é application/json; charset=utf-8. Os timestamps são ISO 8601 em UTC.

POST /consultations

Cria uma consulta nova. Debita o preço B2B do plano do saldo em R$ da empresa (companies.balance_cents). Retorna 201 Created com o registro.

Request body

Exemplo

curl -X POST https://suacapivara.com.br/api/v1/consultations \
  -H "Authorization: Bearer cap_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "cpf-investigacao",
    "target": "12345678900",
    "external_reference": "ticket-42",
    "cost_center": "comercial-sp"
  }'

Response (201)

{
  "id": "a1b2c3d4-...",
  "status": "paid",
  "category": "cpf",
  "plan_id": "cpf-investigacao",
  "target": "12345678900",
  "external_reference": "ticket-42",
  "pdf_url": null,
  "created_at": "2026-05-22T15:43:00.000Z",
  "completed_at": null
}

status começa em paid (saldo já debitado) e vira processing → completed. Quando ficar completed, o pdf_url é populado e disparamos o webhook consultation.completed.

GET /consultations/:id

Retorna o status atual e o PDF (quando pronto).

curl https://suacapivara.com.br/api/v1/consultations/a1b2c3d4-... \
  -H "Authorization: Bearer cap_live_..."

# Pra incluir o JSON estruturado do resultado:
curl 'https://suacapivara.com.br/api/v1/consultations/a1b2c3d4-...?include=result' \
  -H "Authorization: Bearer cap_live_..."

Response (200)

{
  "id": "a1b2c3d4-...",
  "status": "completed",
  "category": "cpf",
  "plan_id": "cpf-investigacao",
  "target": "12345678900",
  "external_reference": "ticket-42",
  "pdf_url": "https://...supabase.co/storage/.../report.pdf?signed=...",
  "amount_cents": 990,
  "folhas_used": 0,
  "created_at": "2026-05-22T15:43:00.000Z",
  "completed_at": "2026-05-22T15:43:08.000Z",
  "result": {
    /* presente apenas se ?include=result */
  }
}

amount_cents é o preço B2B do plano debitado do saldo (em centavos). O campo legado folhas_used continua na resposta apenas pra retrocompatibilidade — sempre 0 no modelo atual.

GET /consultations

Lista paginada de consultas da empresa. Filtros opcionais por status e ref.

curl 'https://suacapivara.com.br/api/v1/consultations?status=completed&limit=50' \
  -H "Authorization: Bearer cap_live_..."

Status de consulta

Idempotência

Envie external_reference com um valor único do seu lado (UUID, ID interno, ticket, etc). Se você reenviar a mesma external_reference pra mesma empresa, devolvemos a consulta existente com status 200 OK em vez de criar uma nova.

Rate limits

Padrão: 60 chamadas / minuto por chave. Configurável por chave no painel. Acima do limite retorna 429 Too Many Requests com header retry-after em segundos.

Códigos de erro

IDs de plano e preço B2B

Cada chamada da API debita o precoB2B do plano consultado direto do saldo da empresa em balance_cents. Para reduzir o custo efetivo, escolha pacotes Manada maiores (mais bônus em saldo).

Webhooks

Pra receber eventos em tempo real (consulta pronta, falha, pagamento confirmado), cadastre um endpoint em /empresa/webhooks.