Documentação da API

A API é REST/JSON. Toda rota exige uma API key. Os endpoints cobrem consulta de risco, decisão automática, registro de sinais, KYC com foto e verificação de identidade com enriquecimento por fontes públicas.

Envie a API key no cabeçalho Authorization (Bearer). As chaves começam com cfy_live_. Gere uma com npm run db:seed.

Authorization: Bearer cfy_live_xxxxxxxxxxxxxxxx

Mande um identificador e o seu limite. A resposta já vem com APPROVE, REVIEW ou DENY.

curl -X POST https://compliancefy.com.br/api/v1/decision \
  -H "Authorization: Bearer $CFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "fraudster@example.com", "denyAbovePercent": 50 }'

{
  "decision": "DENY",
  "fraudRatePct": 86,
  "complaints": 6, "validations": 1, "networkSize": 7,
  "reason": "Taxa de fraude 86% ≥ limite de negação 50%."
}

Se query, ip ou hwid estiverem na sua blocklist, a resposta vem DENY com blockedByYou: true. Gerencie a lista em Painel → Bloqueios.

Retorna o score de risco, os identificadores vinculados e os reports.

curl -X POST https://compliancefy.com.br/api/v1/lookup \
  -H "Authorization: Bearer $CFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "fraudster@example.com" }'

{
  "found": true,
  "risk": {
    "score": 86, "band": "HIGH",
    "complaints": 6, "validations": 1, "networkSize": 7,
    "fraudRate": 0.86, "fraudRatePct": 86
  },
  "identifiers": [ { "type": "EMAIL", "value": "fr*******@example.com" } ],
  "reports": [ { "type": "MED", "amountCents": 80000, "reportedBy": "Acme" } ]
}

Opcional: envie denyThreshold (0–1) para receber também um objeto decision. Sem histórico, found=false e score 0.

Registra um evento de compliance sobre uma entidade.

curl -X POST https://compliancefy.com.br/api/v1/reports \
  -H "Authorization: Bearer $CFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": ["cliente@email.com", "529.982.247-25"],
    "type": "CHARGEBACK",
    "amountCents": 49900,
    "reference": "TX-1001"
  }'

E-mail, CPF, CNPJ, telefone e IP são detectados automaticamente. Para valores opacos como HWID, use o formato tipado: { "type": "HWID", "value": "abc123" }. Reports do tipo MED exigem comprovação e passam pela análise no painel.

O KYC Pro é o nosso front-end de verificação pronto: um pop-up responsivo que você abre para o titular — sem construir tela nenhuma. No celular ele usa a câmera do aparelho; as fotos são comprimidas no cliente antes do envio.

Onde abrir: painel → KYC → KYC Pro → Abrir verificação. Os checks executados seguem as configurações de KYC da organização (documento, selfie, prova de vida, PEP). Cada verificação aparece no histórico com as fotos anexadas.

Prefere a sua própria interface? Use o KYC Transparente (POST /api/v1/kyc, abaixo) — mesmo motor, mesmas regras.

Coloque o KYC Pro dentro do seu produto. Crie uma sessão e abra a URL (ou embuta via iframe) para o cliente final concluir a verificação. No painel: KYC → KYC Pro no seu sistema → Gerar link.

curl -X POST https://compliancefy.com.br/api/v1/kyc/sessions \
  -H "Authorization: Bearer $CFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "pedido-123", "redirectUrl": "https://seusite.com/ok" }'

{
  "id": "ckyc_…",
  "status": "PENDING",
  "url": "https://app.compliancefy…/kyc/ckyc_…",
  "embed": "<iframe src=\"…/kyc/ckyc_…\" allow=\"camera\" …></iframe>"
}

Leia o resultado quando o cliente terminar:

GET /api/v1/kyc/sessions/{id}
{
  "id": "ckyc_…",
  "status": "COMPLETED",
  "reference": "pedido-123",
  "result": { "status": "VERIFIED", "score": 100 }
}

Embutido em iframe, a página avisa o site pai via postMessage ({ source: "compliancefy-kyc", type: "kyc:done", verdict, score }) e redireciona para redirectUrl ao final. KYC inconclusivo vai para a fila de análise da Compliancefy e o status atualiza depois.

Verificação real: o número do documento é validado por dígito verificador (CPF/CNPJ), as fotos (documento e selfie) são decodificadas e validadas, roda triagem PEP e o histórico da rede é considerado. Envie as imagens em base64 (data URL ou base64 puro).

curl -X POST https://compliancefy.com.br/api/v1/kyc \
  -H "Authorization: Bearer $CFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cliente@email.com",
    "fullName": "Maria Silva",
    "documentNumber": "111.444.777-35",
    "documentImage": "data:image/jpeg;base64,/9j/4AAQ...",
    "selfieImage": "data:image/jpeg;base64,/9j/4AAQ..."
  }'

{
  "status": "VERIFIED",
  "level": "FULL",
  "score": 100,
  "checks": { "document": true, "selfie": true, "liveness": true, "pep": false },
  "reasons": []
}

Quais checks rodam depende das configurações de KYC da organização. Retorna 409 kyc_disabled se o KYC estiver desligado. No painel há uma interface de upload das fotos.

Valida CPF/CNPJ, confere na base, traz o último KYC e enriquece com fontes públicas (BrasilAPI para CNPJ, DDD para telefone, heurística de domínio para e-mail).

curl -X POST https://compliancefy.com.br/api/v1/identity \
  -H "Authorization: Bearer $CFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "12.345.678/0001-99" }'

{
  "documentValid": true,
  "knownToNetwork": false,
  "risk": { "score": 0, "band": "LOW", "fraudRatePct": 0 },
  "kyc": null,
  "enrichment": {
    "cnpj": { "source": "brasilapi", "razaoSocial": "EMPRESA LTDA",
              "situacao": "ATIVA", "uf": "SP", "municipio": "SÃO PAULO" }
  }
}

O enriquecimento não depende só da nossa base. É best-effort: se a fonte estiver lenta/indisponível, volta vazio sem quebrar a resposta.

Rotas internas de autofill usadas pelo cadastro: GET /api/lookup/cnpj?cnpj= e GET /api/lookup/cep?cep=.

{ "error": { "code": "unauthorized", "message": "Invalid or missing API key." } }