otimizapro.com/b-check · api rest

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

Uma chave, um endpoint, o catálogo inteiro. Consulta de CNPJ, quadro societário, vínculos entre sócios e cadastros restritivos em JSON normalizado, com lote de até 100 por chamada, webhook assinado para o que depende de fonte lenta, idempotência de 24h para o retry da sua esteira e audit log de quem consultou o quê.

Gerar minha API key sandbox não consome crédito Ver exemplos REST

Documentação direta, sem SDK obrigatório. Sandbox roda a consulta de verdade sem debitar. Suporte técnico em PT-BR.

Autenticação por chave Bearer

Cada conta gera N chaves de API, separadas por ambiente (sandbox / produção). A autenticação é via header Authorization: Bearer <api_key> padrão REST clássico, sem assinatura HMAC, sem OAuth dance. A base de todas as chamadas é https://kyc.otimizapro.com/api/v1.

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

# A chave carrega o ambiente no próprio prefixo: prod_… ou sandbox_…
# Em sandbox a consulta roda de verdade, mas não debita crédito.

Boas práticas:

Chave por ambienteNunca usar chave de prod em sandbox e vice-versadisponível
Uma chave por sistemaChave separada por integração facilita revogar sem parar o restodisponível
Escopo por SKULimitar a chave aos SKUs que o sistema realmente consomeroadmap
IP allowlistRestringir a chave aos IPs da sua esteiraroadmap

Exemplos REST por grupo de consulta

Um endpoint só para tudo: POST /consultas, com o slug do produto no corpo. Resposta unificada: resultado (normalizado) + fonte (de onde veio) + creditos_consumidos + id para auditoria. O catálogo completo de slugs sai em GET /produtos.

Situação cadastral do CNPJ: Pessoa Jurídica

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

# Request
curl -X POST https://kyc.otimizapro.com/api/v1/consultas \
  -H "Authorization: Bearer $OTIMIZA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"produto":"pj.situacao-cnpj",
       "input":{"cnpj":"00.000.000/0001-00"}}'

# Response 200 OK (resumo)
{
  "id": "01J...",
  "produto": "pj.situacao-cnpj",
  "status": "concluida",
  "creditos_consumidos": 1,
  "resultado": {
    "razao_social": "...",
    "situacao": "ATIVA",
    "cnae_principal": "...",
    "uf": "SP",
    "data_abertura": "..."
  },
  "fonte": "BrasilAPI / Receita Federal",
  "ambiente": "prod"
}

Quadro societário (QSA): quem manda na empresa

Alvo: identificar sócios e administradores antes de assinar contrato, abrir crédito B2B ou aprovar um seller.

# Request
curl -X POST https://kyc.otimizapro.com/api/v1/consultas \
  -H "Authorization: Bearer $OTIMIZA_KEY" \
  -d '{"produto":"pj.qsa",
       "input":{"cnpj":"00.000.000/0001-00"}}'

# Response 200 OK (resumo)
{
  "id": "01J...",
  "produto": "pj.qsa",
  "status": "concluida",
  "creditos_consumidos": 1,
  "resultado": {
    "razao_social": "...",
    "qsa": [
      {"nome": "...", "qualificacao": "Sócio-Administrador"}
    ]
  },
  "fonte": "BrasilAPI / Receita Federal"
}

Pack básico PJ: cadastro e listas restritivas

Alvo: PLD/FT em fintech regulada, KYB corporativo, due diligence de fornecedor.

# Um pack roda vários checks e devolve o consolidado
curl -X POST https://kyc.otimizapro.com/api/v1/consultas \
  -H "Authorization: Bearer $OTIMIZA_KEY" \
  -d '{"produto":"pj.pack-basico",
       "input":{"cnpj":"00.000.000/0001-00"}}'

# Response 200 OK (resumo)
{
  "produto": "pj.pack-basico",
  "status": "concluida",
  "creditos_consumidos": 4,
  "resultado": {
    "situacao_cnpj": {...},
    "ceis": {"status": "limpo", "hits": []},
    "cnep": {"status": "limpo", "hits": []},
    "lista_suja_mte": {"status": "limpo", "hits": []},
    "consolidado": {"tem_restricao": false}
  },
  "fonte": "bundle: Receita + CGU + MTE"
}

Lote, até 100 consultas numa chamada

Alvo: varrer a base de fornecedores, requalificar carteira, rodar a esteira de cadastro do dia.

# Request
curl -X POST https://kyc.otimizapro.com/api/v1/consultas:batch \
  -H "Authorization: Bearer $OTIMIZA_KEY" \
  -d '{"itens":[
       {"produto":"pj.situacao-cnpj","input":{"cnpj":"..."}},
       {"produto":"pj.qsa","input":{"cnpj":"..."}}
     ]}'

# Response 200 OK
{
  "count": 2,
  "itens": [
    {"produto":"pj.situacao-cnpj","status":"concluida", ...},
    {"produto":"pj.qsa","status":"concluida", ...}
  ]
}

# Saldo insuficiente para o lote inteiro → 402, nada é debitado

Consultas assíncronas com webhook

Algumas fontes públicas são lentas demais para caber num request HTTP. Nesses casos a consulta nasce com status: "pendente" e HTTP 202, já com o id dela, e o resultado chega por webhook assinado quando fica pronto. Você não segura conexão aberta esperando tribunal.

# 1. A consulta volta na hora, ainda pendente
POST /api/v1/consultas
→ 202 Accepted
{ "id": "01J...", "produto": "...", "status": "pendente" }

# 2. Webhook entregue quando conclui (assinado HMAC-SHA256)
POST https://seu-endpoint.example.com/otimiza-webhook
Headers:
  X-Otimiza-Signature: sha256=...
  X-Otimiza-Event: consulta.concluida
Body:
  { "id": "01J...",
    "produto": "...",
    "status": "concluida",
    "resultado": {...} }

Prefere não expor webhook? Faça polling em GET /api/v1/consultas/<id>. Você registra o endpoint de callback uma vez em POST /api/v1/webhooks, ou manda callback_url na própria consulta.

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 a resposta original
curl -X POST https://kyc.otimizapro.com/api/v1/consultas \
  -H "Idempotency-Key: 4b9c1d2e-..." \
  -H "Authorization: Bearer $OTIMIZA_KEY" \
  -d '{"produto":"pj.situacao-cnpj","input":{"cnpj":"..."}}'

# O replay vem marcado no header:  X-Idempotent-Replay: true

Rate limit padrão: 60 requisições por minuto por chave. Precisa de mais? É ajuste de plano, fale com a gente antes de escalar a esteira.

Códigos que a sua integração precisa tratar:

202Consulta aceita, ainda pendente: resultado vem por webhook ou pollingstatus
402Saldo de créditos insuficiente: nada foi debitadostatus
422Consulta falhou. Falha nossa (fonte fora do ar) estorna o crédito; erro de input, nãostatus
429Rate limit estourado: reduza a concorrência e repitastatus

Consulte saldo e consumo a qualquer momento em GET /api/v1/saldo e GET /api/v1/cobrancas.

SDKs e exemplos prontos

Não existe SDK obrigatório, e nem SDK, por enquanto. A API é um POST com JSON e um header de autorização: qualquer HTTP client resolve, e os exemplos em curl acima traduzem direto para a sua linguagem. É de propósito: preferimos uma superfície pequena e estável a um wrapper que envelhece.

Exemplos em curlCobrem todos os endpoints: copie e coledisponível
Node.js / TypeScriptHelper de verificação de assinatura de webhookroadmap
PythonWrapper de consultas e loteroadmap
Coleção Postman e spec OpenAPIPeça pelo suporte enquanto não publicamosroadmap

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.