API de integração da Kapta360

Cada consulta gera o relatório completo do CPF: dados cadastrais e de contato, endereços, participações societárias, restrições financeiras, protestos, informações do Sistema de Informações de Crédito (SCR) e a classificação de risco calculada pela Kapta360. Só o relatório completo é entregue e cobrado: se alguma parte não puder ser obtida, a consulta falha e o crédito volta.

• Endereço de produção: https://api.kapta360.com/v1 · homologação: https://api-homolog.kapta360.com/v1.
• JSON em UTF-8, datas em ISO 8601 (UTC), valores em reais como número decimal.
• Servidor a servidor: nunca use o token em navegador, aplicativo ou repositório de código. A API não aceita chamadas de navegador (sem CORS).
• 1 crédito = 1 relatório completo, o mesmo saldo do painel. Os relatórios de produção também aparecem no histórico do seu painel.

1. Peça a liberação da API ao suporte da Kapta360 (a API vem desligada em toda conta).
2. No painel, abra Integração, leia e aceite os Termos de Uso da API.
3. Crie um token de testes (k360_test_…): dados fictícios, sem cobrança.
4. Confira o token com GET /v1/conta e faça a primeira consulta com um CPF da seção Ambiente de testes.
5. Configure o webhook, trate os erros e só então crie o token de produção (k360_live_…).

# 1) Cria a consulta (com o token de testes, use os CPFs da seção "Ambiente de testes")
curl -X POST https://api.kapta360.com/v1/consultas \
  -H "Authorization: Bearer $KAPTA360_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-12345" \
  -H "Prefer: wait=30" \
  -d '{"cpf":"00000000191","finalidade":"ANALISE_DE_RISCO_DE_CREDITO","autorizacaoTitular":true,"referenciaExterna":"pedido-12345"}'

# 2) Acompanha até CONCLUIDA ou FALHOU (espera até 30 s por chamada)
curl https://api.kapta360.com/v1/consultas/$CONSULTA_ID \
  -H "Authorization: Bearer $KAPTA360_TOKEN" \
  -H "Prefer: wait=30"

# 3) Baixa o PDF
curl -o relatorio.pdf https://api.kapta360.com/v1/consultas/$CONSULTA_ID/pdf \
  -H "Authorization: Bearer $KAPTA360_TOKEN"

Envie o token no cabeçalho Authorization: Bearer k360_…. O prefixo define o ambiente: k360_live_ (produção, cobra créditos) ou k360_test_ (testes). Um token só enxerga as consultas do próprio ambiente.

• Escopos: consultas:criar, consultas:ler (inclui o PDF) e saldo:ler (saldo e extrato). GET /v1/conta aceita qualquer escopo.
• Opcional: lista de IPs ou faixas permitidas por token, e validade.
• O segredo aparece uma única vez, na criação. Em caso de suspeita de vazamento, revogue na área Integração: vale na hora.
• Respostas: 401 para token ausente, inválido, revogado ou expirado; 403 para token válido sem permissão (IP, escopo, conta bloqueada, API desligada, termos pendentes).

POST /v1/consultas responde 202 com a consulta em NA_FILA e o cabeçalho Location. Ela passa a PROCESSANDO e termina em CONCLUIDA (relatório e PDF) ou FALHOU (crédito devolvido). O tempo típico é de 30 a 90 segundos.

• Para saber quando terminou: receba o webhook, ou consulte GET /v1/consultas/{id} com Prefer: wait=N (até 60 s de espera por chamada) — o mesmo cabeçalho vale no POST.
• Prazos máximos: 1 h até a coleta começar (na fila ou aguardando capacidade) e 20 min de coleta a partir daí. Depois disso a consulta falha (FILA_EXPIRADA ou PRAZO_ESGOTADO) e o crédito volta.
• Se o PDF não ficar pronto em 10 min, a consulta conclui com pdf.disponivel = false e o PDF chega depois (evento consulta.pdf_disponivel).
• Cobrança: o crédito é reservado na criação (RESERVADO), confirmado na conclusão (COBRADO) e devolvido se a consulta falhar (DEVOLVIDO). No ambiente de testes: SEM_COBRANCA.

{
  "id": "8b6f1d2e-3c4a-4f5b-9a8c-7d6e5f4a3b2c",
  "status": "CONCLUIDA",
  "fase": null,
  "ambiente": "live",
  "cpfMascarado": "***.456.789-**",
  "finalidade": "ANALISE_DE_RISCO_DE_CREDITO",
  "referenciaExterna": "pedido-12345",
  "criadoEm": "2026-10-19T14:02:11.000Z",
  "concluidaEm": "2026-10-19T14:03:05.000Z",
  "cobranca": {
    "situacao": "COBRADO",
    "creditos": 1,
    "reaproveitada": false,
    "saldoRestante": null
  },
  "numeroRelatorio": "2026-000123",
  "validade": {
    "expiraEm": "2027-01-17T14:03:05.000Z",
    "expirado": false
  },
  "erro": null,
  "pdf": {
    "disponivel": true,
    "url": "https://api.kapta360.com/v1/consultas/8b6f1d2e-3c4a-4f5b-9a8c-7d6e5f4a3b2c/pdf"
  },
  "relatorio": { "versao": "1", "metadados": { … }, "titular": { … }, "classificacao": { … }, "restricoes": { … }, "scr": { … }, "avisos": [] }
}

Todo POST /v1/consultas exige Idempotency-Key (8 a 64 caracteres entre letras, números e . _ : -), única por pedido e válida por 7 dias. Repetir com a mesma chave devolve a mesma consulta, com Idempotent-Replayed: true, sem cobrar de novo. A mesma chave com outro corpo é recusada (IDEMPOTENCY_KEY_REUTILIZADA).

Já existe consulta em andamento para o mesmo CPF (com outra chave)? A resposta é 409 CONSULTA_EM_ANDAMENTO com o id dela em erro.detalhes.consultaId, sem cobrança.

Envie reaproveitarDias (1 a 7) para receber, sem cobrar, um relatório completo do mesmo CPF gerado pela API para a sua conta nesse período: a resposta é 200 imediato, com o mesmo número de relatório e o mesmo PDF, e cobranca.reaproveitada = true. Sem relatório recente, segue como uma consulta nova (cobrada).

Corpo do POST: cpf (com ou sem pontuação), finalidade, autorizacaoTitular: true, e opcionais referenciaExterna e reaproveitarDias. Esquemas completos no OpenAPI.

Quando a consulta conclui, relatorio traz os grupos versao, metadados, titular, contatos, enderecos, participacoesSocietarias, indicadores, classificacao, restricoes, scr, avisos. Campos sem informação vêm como null (nunca omitidos); listas vazias, como []. Ausência de registros é resultado válido e vem com aviso em avisos[] (ex.: SCR_SEM_RELACIONAMENTO). Ignore campos novos que aparecerem: eles podem ser acrescentados sem aviso.

GET /v1/consultas/{id}/pdf devolve o mesmo relatório da impressão do painel (A4), com o nome kapta360-<numero>.pdf. Use quando pdf.disponivel = true. Ainda em geração: 409 PDF_EM_GERACAO com Retry-After. A ETag é o SHA-256 do arquivo: com If-None-Match, a resposta é 304. No ambiente de testes o PDF leva a marca d'água "AMOSTRA — DADOS FICTÍCIOS".

Configure na área Integração um endereço https:// por ambiente e os eventos: consulta.concluida, consulta.falhou, consulta.pdf_disponivel e saldo.baixo (só produção, a partir do limite de créditos que você escolher). O botão de teste envia webhook.teste. O corpo não traz o relatório: busque-o pelo link.

{
  "id": "c0a8012e-7f3d-4b1a-9e2c-5d4f3a2b1c0d",
  "evento": "consulta.concluida",
  "criadoEm": "2026-10-19T14:03:06.000Z",
  "ambiente": "live",
  "dados": {
    "consulta": {
      "id": "8b6f1d2e-3c4a-4f5b-9a8c-7d6e5f4a3b2c",
      "status": "CONCLUIDA",
      "numeroRelatorio": "2026-000123",
      "cpfMascarado": "***.456.789-**",
      "referenciaExterna": "pedido-12345",
      "cobranca": "COBRADO",
      "reaproveitada": false,
      "erro": null,
      "pdf": {
        "disponivel": true
      },
      "links": {
        "consulta": "https://api.kapta360.com/v1/consultas/8b6f1d2e-3c4a-4f5b-9a8c-7d6e5f4a3b2c",
        "pdf": "https://api.kapta360.com/v1/consultas/8b6f1d2e-3c4a-4f5b-9a8c-7d6e5f4a3b2c/pdf"
      }
    }
  }
}

• Cabeçalhos: Kapta360-Assinatura, Kapta360-Evento, Kapta360-Entrega (id desta entrega) e Kapta360-Tentativa.
• Responda 2xx em até 10 s. Redirecionamentos não são seguidos. O endereço precisa ser um nome de domínio público (IPs internos são recusados).
• Entrega pelo menos uma vez: o mesmo evento pode chegar mais de uma vez — deduplique pelo id do corpo (o reenvio manual mantém o mesmo id).
• Sem 2xx, repetimos (até 11 tentativas, com até 10% de variação nos intervalos):

• Com 50 falhas seguidas e nenhum sucesso em 72 h, o webhook é desativado; corrija, teste e reative na área Integração (eventos perdidos podem ser reenviados de lá).
• Conta bloqueada ou API desligada: as entregas ficam suspensas e voltam se a conta for liberada em até 72 h.

Confira a assinatura antes de usar o corpo. Kapta360-Assinatura: t=<unix>,v1=<hex>, onde v1 é o HMAC-SHA256 do texto "<t>.<corpo cru>" com o segredo do webhook (k360_whsec_…, visível na área Integração). Recuse t com mais de 300 s de diferença do seu relógio. Pode haver mais de um v1: aceite se algum conferir.

const crypto = require("node:crypto");

/** true se o corpo veio da Kapta360. "corpo" é o texto CRU recebido, antes de qualquer JSON.parse. */
function webhookValido(corpo, cabecalho, segredo, toleranciaSeg = 300) {
  const partes = String(cabecalho ?? "").split(",").map((p) => p.trim());
  const t = Number(partes.find((p) => p.startsWith("t="))?.slice(2));
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranciaSeg) return false;
  const esperado = Buffer.from(crypto.createHmac("sha256", segredo).update(`${t}.${corpo}`).digest("hex"));
  return partes
    .filter((p) => p.startsWith("v1="))
    .map((p) => Buffer.from(p.slice(3)))
    .some((r) => r.length === esperado.length && crypto.timingSafeEqual(r, esperado));
}

// Express: o corpo precisa chegar CRU para a assinatura conferir.
app.post("/webhooks/kapta360", express.raw({ type: "application/json" }), (req, res) => {
  const corpo = req.body.toString("utf8");
  if (!webhookValido(corpo, req.get("Kapta360-Assinatura"), process.env.KAPTA360_WEBHOOK_SEGREDO)) {
    return res.sendStatus(400);
  }
  const evento = JSON.parse(corpo);
  // Deduplique por evento.id (pode chegar mais de uma vez), enfileire o trabalho e responda logo.
  res.sendStatus(204);
});

Todo erro vem no envelope abaixo, com um codigo estável (use-o no seu código, não a mensagem) e o requestId — informe-o ao suporte. O mesmo id volta no cabeçalho X-Request-Id.

{
  "erro": {
    "codigo": "SALDO_INSUFICIENTE",
    "mensagem": "Créditos insuficientes. Compre créditos no painel.",
    "requestId": "req_2a216d2d7a1d41529024492ec4ae4113"
  }
}

Motivos de falha de uma consulta (erro.codigo quando status = FALHOU; o crédito é sempre devolvido):

Os limites são por conta e por ambiente e podem ser ajustados pelo suporte; os seus aparecem em GET /v1/conta. Acima deles: 429 LIMITE_EXCEDIDO com Retry-After. Em picos de demanda, a criação pode responder 503 CAPACIDADE_ESGOTADA com Retry-After (sem cobrança). Tokens desconhecidos: 20 tentativas em 10 min bloqueiam o IP por 15 min.

Com um token k360_test_, o caminho é o mesmo da produção (fila, processamento, PDF, webhooks), mas com dados fictícios, sem cobrança, sem entrar no histórico do painel e com número de relatório AMOSTRA-…. O saldo e o extrato são fictícios (amostra: true). Só estes CPFs são aceitos; outros recebem 422 CPF_FORA_DO_AMBIENTE_DE_TESTES:

• Toda consulta declara a finalidade, uma de: ANALISE_DE_RISCO_DE_CREDITO (análise de risco de crédito); CONCESSAO_OU_EXTENSAO_DE_CREDITO (concessão ou extensão de crédito); VENDA_A_PRAZO_OU_TRANSACAO_COM_RISCO_FINANCEIRO (venda a prazo ou outra transação com risco financeiro) (Lei nº 12.414/2011), e autorizacaoTitular: true, confirmando que você obteve a autorização do titular e guarda a prova.
• Você e a Kapta360 atuam como controladoras independentes. É vedado revender, compartilhar ou usar os dados para outra finalidade. Leia os Termos de Uso da API e a Política de Privacidade.
• O titular pode pedir a revisão da classificação de risco, que é automatizada (art. 20 da LGPD), pelo canal indicado na Política de Privacidade.

A versão está no caminho (/v1) e no relatório (relatorio.versao = "1"). Na v1 só entram mudanças compatíveis: novos campos, eventos, códigos de erro e endpoints — trate o desconhecido sem quebrar. Mudanças incompatíveis vêm numa nova versão, com aviso de pelo menos 6 meses antes de a v1 ser desligada.

Fale com o suporte pelo canal do painel e informe o requestId da resposta (ou o id da consulta). Nunca envie o token nem o segredo do webhook: o suporte não precisa deles.