bcheck.otimizapro.com · api rest

Uma API REST para Background Check, KYC e KYB no Brasil.

Uma chave, todos os SKUs. Consulta de CNPJ, quadro societário, CPF, PEP, sanções OFAC/ONU/EU/BCB, CEIS/CNEP, antecedentes, processos, certidões e identidade biométrica em endpoints REST padronizados. JSON normalizado, webhook nativo para consultas assíncronas, idempotency por chave e audit log imutável — fora da caixa.

Gerar minha API key sandbox liberado na hora Ver exemplos REST

Documentação direta, sem SDK obrigatório. Sandbox com créditos cortesia. Suporte técnico em PT-BR.

Autenticação por chave Bearer

Cada conta gera N chaves de API, separadas por ambiente (sandbox / produção) e com escopo configurável (por SKU, por IP, por rate limit). A autenticação é via header Authorization: Bearer <api_key> — padrão REST clássico, sem assinatura HMAC, sem OAuth dance.

# Cabeçalho obrigatório em qualquer chamada
Authorization: Bearer otmza_live_KEY_AQUI
Content-Type: application/json

# Rotação a qualquer momento pelo portal — chave antiga continua válida por 24h

Boas práticas:

Chave por ambienteNunca usar chave de prod em sandbox e vice-versarequired
Escopo por SKULimite a chave aos SKUs que o sistema realmente consomerecommended
IP allowlistRestrinja a chave aos IPs da sua esteirarecommended
Rotação trimestralPolítica de segurança padrão — sem dor de integraçãopolicy

Exemplos REST por grupo de consulta

Cada SKU é um endpoint dedicado. Resposta unificada: payload_raw (bruto do provedor) + payload (normalizado) + audit (quem consultou, quando, em qual chave).

Consulta CNPJ + QSA — Pessoa Jurídica

Alvo: cadastro de fornecedor, abertura de cliente B2B, qualificação seller marketplace.

# Request
curl https://api.bcheck.otimizapro.com/v1/pj/cnpj \
  -H "Authorization: Bearer $OTIMIZA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cnpj":"00.000.000/0001-00",
       "include":["qsa","cnae","certidoes"]}'

# Response 200 OK (resumo)
{
  "sku": "PJ-RF-01",
  "cnpj": "00000000000100",
  "payload": {
    "razao_social": "...",
    "situacao": "ATIVA",
    "qsa": [...],
    "cnae_principal": "...",
    "capital_social": 100000.00
  },
  "audit": {"request_id":"req_...","credits":2,"latency_ms":420}
}

Consulta CPF + Score — Pessoa Física

Alvo: KYC de signatário, validação de sócio, background pré-crédito.

# Request
curl https://api.bcheck.otimizapro.com/v1/pf/cpf \
  -H "Authorization: Bearer $OTIMIZA_KEY" \
  -d '{"cpf":"000.000.000-00",
       "include":["score","processos"]}'

# Response 200 OK (resumo)
{
  "sku": "PF-RF-01",
  "payload": {
    "situacao": "REGULAR",
    "nome": "...",
    "score_credito": {"faixa": "B", "indicador": 720},
    "processos_count": 2
  },
  "audit": {"credits":3,"latency_ms":680}
}

PEP + Sanções consolidadas — Compliance

Alvo: PLD/FT obrigatório em fintech regulada, KYC corporativo.

# Request
curl https://api.bcheck.otimizapro.com/v1/compliance/screening \
  -H "Authorization: Bearer $OTIMIZA_KEY" \
  -d '{"nome":"NOME COMPLETO",
       "cpf":"000.000.000-00",
       "listas":["pep","ofac","onu","bcb","ceis","cnep"]}'

# Response 200 OK (resumo)
{
  "sku": "CO-PEP-01,CO-SAN-01,CO-CEIS-01,CO-CNEP-01",
  "payload": {
    "matches": [],
    "score": 0,
    "decisao_sugerida": "aprovar_automatico"
  }
}

Face match + Liveness — Identidade

Alvo: onboarding remoto regulado, validação documental.

# Request — multipart com selfie e documento
curl https://api.bcheck.otimizapro.com/v1/id/face-match \
  -H "Authorization: Bearer $OTIMIZA_KEY" \
  -F selfie=@selfie.jpg \
  -F documento=@cnh.jpg \
  -F liveness=true

# Response 200 OK (resumo)
{
  "sku": "ID-FCM-01,ID-LIV-01",
  "payload": {
    "match_score": 0.97,
    "liveness_passed": true,
    "documento_extraido": {...}
  }
}

Consultas assíncronas com webhook

Algumas consultas dependem de tribunais ou fontes públicas lentas — antecedentes criminais estaduais, processos judiciais em massa, dossiês de mídia adversa. Em vez de você ficar com timeout HTTP estourado, o Otimiza B-CHECK responde imediatamente com um job_id e dispara um webhook no seu endpoint quando o resultado fica pronto.

# 1. Enfileira a consulta
POST /v1/pf/antecedentes
→ 202 Accepted
{ "job_id": "job_abc123", "estimated_seconds": 180 }

# 2. Webhook entregue quando pronto (assinado HMAC-SHA256)
POST https://seu-endpoint.example.com/otimiza-webhook
Headers:
  X-Otimiza-Signature: sha256=...
  X-Otimiza-Event: query.completed
Body:
  { "job_id": "job_abc123",
    "sku": "PF-ANT-01",
    "status": "completed",
    "payload": {...} }

Você também pode fazer polling via GET /v1/jobs/<job_id> se preferir não expor webhook.

Idempotency, rate limit e paginação

Para evitar cobrar duas vezes a mesma consulta em caso de retry da sua esteira, mande o header Idempotency-Key com um UUID único por intenção de consulta. Resposta ao mesmo idempotency-key em até 24h devolve a resposta original sem consumir créditos extras.

# Idempotente — mesma chave devolve resposta cacheada
curl -X POST https://api.bcheck.otimizapro.com/v1/pj/cnpj \
  -H "Idempotency-Key: 4b9c1d2e-..." \
  -H "Authorization: Bearer $OTIMIZA_KEY" \
  ...

Rate limit padrão: 60 req/min por chave (sandbox) e 600 req/min (produção). Headers de resposta:

X-RateLimit-LimitJanela de 60sheader
X-RateLimit-RemainingQuanto resta na janelaheader
X-RateLimit-ResetTimestamp Unix do resetheader
X-Request-IdUse no suporteheader

Listagens paginam por cursor — pegue next_cursor da resposta e passe em ?cursor=....

SDKs e exemplos prontos

A API foi desenhada para ser direta o suficiente para você não precisar de SDK no MVP — qualquer HTTP client serve. Mas mantemos exemplos canônicos:

Node.js / TypeScriptfetch nativo + helper de assinatura webhookdisponível
Pythonrequests + helper de paginação cursordisponível
Gonet/http + struct typesroadmap 2026
PHP & JavaGuzzle / OkHttpsob demanda Enterprise

Coleção Postman + spec OpenAPI 3.1 disponíveis ao criar conta.

Pegue uma API key, rode em sandbox, depois ligue produção.

Sandbox cortesia já liberado no cadastro. Sem cartão, sem fidelidade, com a mesma governança que sustenta o KYC interno da Plataforma Otimiza 3.0.

Gerar minha API key teste com créditos cortesia

Suporte técnico: check@otimiza.pro · Voltar à página principal.