API v1

Documentação de integração

A Consultei consulta 5 bureaus brasileiros em paralelo, aplica triangulação por ML sobre as respostas e devolve um veredito tipado por CPF. Mediana de 180ms, p99 de 480ms, timeout 2000ms. Esta documentação cobre a API REST v1; as SDKs TypeScript, Go e PHP são wrappers finos sobre ela.

Modelos mentais

• Veredito é a decisão final: approved, review, flagged ou rejected.
• Score é um inteiro de 0–1000, saída do modelo proprietário que pondera confiabilidade histórica por bureau.
• audit_id é a chave única de cada consulta, com retenção de 90 dias nos planos Start e Scale, indefinida no Enterprise.
• Fallback acontece por bureau, não por pedido: se Serasa falhar, a decisão sai com 4 fontes e flag partial: true.

Autenticação

Todas as requisições exigem dois headers:

Authorization: Bearer kyc_live_7f3a2c8b1e9d4a60
X-Consultei-Signature: sha256=a3f8c7...

Assinatura HMAC

A assinatura é um HMAC-SHA256 do body cru, usando o signing_secret do seu projeto (dashboard · Settings · Keys). Em pseudo-código:

sig = hmac_sha256(signing_secret, request_body)
header = "sha256=" + hex(sig)

Toda SDK oficial assina automaticamente. Para fallback REST, veja o exemplo em Go.

Verificação de identidade

Endpoint principal. Consulta Receita Federal, SPC, Serasa, Serpro e BCB em paralelo, aplica o modelo de triangulação e devolve veredito.

Request

curl -X POST https://api.consultei.io/v1/verify/identity \
  -H "Authorization: Bearer kyc_live_7f3a2c8b1e9d4a60" \
  -H "X-Consultei-Signature: sha256=a3f8c7..." \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "123.456.789-09",
    "full_name": "Maria Silva",
    "date_of_birth": "1992-04-15",
    "metadata": { "operator_user_id": "u_8821" }
  }'

Response · 200 OK

{
  "audit_id": "aud_01HZX7P2M9V4B6",
  "cpf": "123.456.789-09",
  "verdict": "approved",
  "score": 847,
  "confidence": 0.92,
  "latency_ms": 184,
  "sources": {
    "receita":  { "status": "hit", "ms": 82,  "data": { "situacao": "regular", "nome_match": true } },
    "spc":      { "status": "hit", "ms": 147, "data": { "pendencias": 0 } },
    "serasa":   { "status": "hit", "ms": 164, "data": { "score": 820, "restricoes": 0 } },
    "serpro":   { "status": "hit", "ms": 98,  "data": { "nome_oficial": "Maria Silva" } },
    "bcb":      { "status": "hit", "ms": 112, "data": { "pep": false, "sanctions": [] } }
  },
  "partial": false,
  "model_version": "v3.1.4"
}

Parâmetros

Verificação de idade mínima

Cruza a data de nascimento informada com a base nominal da Serpro e calcula idade na data de referência (default: hoje).

{ "cpf": "287.455.110-04", "minimum_age": 18 }

→ 200
{
  "audit_id": "aud_01HZX7Q9R2S8T4",
  "verdict": "rejected",
  "age": 16,
  "reason": "under_minimum_age",
  "source": "serpro",
  "latency_ms": 94
}

PEP e listas de sanções

Consulta BCB (lista PEP nacional) + OFAC + ONU + EU em um único call. Útil pra onboarding regulado (Res. COAF 29).

{ "cpf": "412.908.733-21", "lists": ["pep", "ofac", "un", "eu"] }

→ 200
{
  "audit_id": "aud_01HZX7RQ4V7W8X",
  "verdict": "flagged",
  "matches": [
    { "list": "pep", "role": "deputado_federal", "since": "2023-02-01" }
  ],
  "latency_ms": 112
}

Autoexclusão nacional

Consulta a base pública de autoexcluídos da SPA-MF em tempo real. Obrigatório para operadores regulados antes de aceitar aposta.

{ "cpf": "876.543.210-99" }

→ 200
{
  "audit_id": "aud_01HZX7S8T9U1V2",
  "verdict": "approved",
  "excluded": false,
  "last_checked": "2026-10-29T05:12:33Z"
}

Recuperar log de auditoria

Devolve o payload completo de uma consulta anterior, incluindo responses crus de cada bureau. Retenção: 90 dias (Start/Scale), indefinida (Enterprise).

curl https://api.consultei.io/v1/audit/aud_01HZX7P2M9V4B6 \
  -H "Authorization: Bearer kyc_live_..."

Webhooks

Para fluxos assíncronos, você registra um webhook (dashboard · Settings · Webhooks) e recebe POST a cada evento. Assinatura idêntica à do request de saída (X-Consultei-Signature).

Eventos

Exemplo de payload

POST https://seu-dominio.com/consultei/webhook
X-Consultei-Signature: sha256=b7e2d4...

{
  "event": "verify.completed",
  "audit_id": "aud_01HZX7P2M9V4B6",
  "verdict": "approved",
  "score": 847,
  "created_at": "2026-10-29T05:12:33Z",
  "metadata": { "operator_user_id": "u_8821" }
}

Códigos de erro

Rate limits

Headers de resposta em toda chamada:

X-RateLimit-Limit: 25
X-RateLimit-Remaining: 23
X-RateLimit-Reset: 1730178392

SDKs

Instalação por linguagem. Todas assinam HMAC automaticamente e lidam com retry em 503/504.

TypeScript

npm install @consultei/sdk

import { Consultei } from "@consultei/sdk";
const kyc = new Consultei({ apiKey: process.env.KYC_KEY! });
const r = await kyc.verify.identity({ cpf: "123.456.789-09" });
if (r.verdict === "approved") grantAccess(r);

Go

go get github.com/consultei/go-sdk

cli := consultei.New(os.Getenv("KYC_KEY"))
r, err := cli.Verify.Identity(ctx, &consultei.IdentityReq{Cpf: "123.456.789-09"})
if r.Verdict == consultei.Approved { grant(r) }

PHP

composer require consultei/sdk

$kyc = new \Consultei\Client(getenv('KYC_KEY'));
$r = $kyc->verify->identity(['cpf' => '123.456.789-09']);
if ($r->verdict === 'approved') { grant($r); }

Fallback REST com HMAC (Go cru)

body := []byte(`{"cpf":"123.456.789-09"}`)
mac := hmac.New(sha256.New, []byte(signingSecret))
mac.Write(body)
sig := "sha256=" + hex.EncodeToString(mac.Sum(nil))

req, _ := http.NewRequest("POST", "https://api.consultei.io/v1/verify/identity", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("X-Consultei-Signature", sig)
req.Header.Set("Content-Type", "application/json")

Changelog

1. 2026-10-28

   Modelo v3.1.4 — melhoria de 2,3pp na precisão em CPFs com nome parcial. Breaking para quem usa o campo score raw sem threshold.

2. 2026-10-15

   Novo endpoint /verify/selfexclusion — integração direta com a base SPA-MF. Resposta em tempo real, sem cache.

3. 2026-09-30

   SDK Go 1.4.0 — context.Context propagation + retry configurável. Backward compatible.

4. 2026-09-20

   Webhook bureau.degraded — avisa antes do SLA quebrar. Útil pra ligar logs do seu APM.