Como integrar consulta de CPF/CNPJ via API no seu sistema

Tem sistema rodando (CRM, ERP, antifraude, painel interno) e quer integrar consultas de CPF/CNPJ/veicular sem o time clicando em painel? A API B2B da Capivara faz isso em REST com Bearer token + webhook HMAC.

Visão geral em 3 etapas

1. Crie conta empresa e recarregue créditos no painel
2. Gere uma API key (cap_live_...) em /empresa/api
3. Faça POST em /api/v1/consultations com Bearer token

Pronto. Quando a consulta ficar pronta, mandamos webhook com PDF anexado pro endpoint que você cadastrar.

Exemplo de chamada

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"
  }'

Resposta imediata

A API responde em 200-500ms com o status inicial. Não bloqueia: o processamento (consulta de bureaus + geração de PDF) roda em background.

{
  "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:00Z"
}

Webhook quando ficar pronta

Quando o PDF estiver pronto (geralmente em 5-20 segundos), mandamos POST pro endpoint que você cadastrou em /empresa/webhooks:

POST https://seusistema.com/webhooks/capivara
x-capivara-signature: t=1714994580,v1=ab12cd34...
x-capivara-event: consultation.completed

{
  "id": "evt_a1b2c3d4-...",
  "type": "consultation.completed",
  "data": {
    "consultation_id": "...",
    "external_reference": "ticket-42",
    "pdf_url": "https://...supabase.co/storage/.../report.pdf",
    "status": "completed"
  }
}

Validação HMAC (timing-safe)

Sempre valide o header x-capivara-signature. Caso contrário, qualquer um pode forjar requisições pro seu endpoint:

import crypto from "crypto";

function verifyCapivara(rawBody, sigHeader, secret) {
  const parts = sigHeader.split(",").reduce((acc, p) => {
    const [k, v] = p.split("=");
    acc[k] = v;
    return acc;
  }, {});

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1)
  );
}

Idempotência via external_reference

Envie external_reference com um ID único do seu lado (UUID, ID interno, ticket). Se você reenviar a mesma external_reference pra mesma empresa, a gente devolve a consulta existente com 200 OKem vez de criar uma nova. Isso protege contra duplicação por:

• Retry de rede (timeout do seu lado)
• Workers concorrentes processando a mesma fila
• Botão clicado duas vezes na UI

Boas práticas em produção

• Não exponha a API key no frontend — sempre chame do servidor
• Use external_reference em toda chamada
• Trate webhook como source of truth, não polling em /v1/consultations/:id
• Responda 200 OK ao webhook em até 15s, processe pesado em background
• Reaja a 429 (rate limit) com backoff exponencial
• Monitore folhas — recarga automática quando saldo < 100

Rate limits

Padrão: 60 chamadas/min por chave. Aumentamos pra plano enterprise sem custo extra (fale com o time). Resposta 429 tem headerRetry-After: 60.

Próximo passo

Leia a referência completa, a doc de webhooks ou crie sua conta empresa e gere a primeira chave em /cadastro.