# Compliancefy — Referência da API

> Rede colaborativa antifraude, verificação de pagamentos, KYC e enriquecimento por fontes públicas.
> Este documento é auto-contido: cole-o inteiro num assistente de IA (ChatGPT, Claude, Cursor, etc.) e peça para gerar a integração no seu stack.

- **Base URL:** `https://compliancefy.com.br`
- **Formato:** JSON em todas as requisições e respostas (`Content-Type: application/json`).
- **Autenticação:** cabeçalho `Authorization: Bearer <API_KEY>`.
- **Como obter a chave:** Painel → Segurança → criar chave de API. A chave só aparece uma vez; guarde com segurança.

---

## Autenticação

Toda chamada à API (`/api/v1/*`) exige uma chave de API no cabeçalho:

```
Authorization: Bearer cfy_live_key...
```

Chave ausente, inválida ou revogada → `401 unauthorized`.
Chave sem o escopo necessário → `403 forbidden`.

Escopos:

| Escopo | Libera |
|---|---|
| `lookup` | `/decision`, `/lookup`, `/identity`, `/kyc`, `/kyc/sessions`, `/sources`, `/name` |
| `report` | `/reports` |

---

## Convenções

- Identificadores comuns (e-mail, CPF, CNPJ, telefone, IP) são **detectados automaticamente** pelo formato.
- Para valores opacos (ex.: `HWID`), use o formato **tipado**: `{ "type": "HWID", "value": "abc123" }`.
- Valores monetários em **centavos** (`amountCents`), moeda BRL por padrão.
- Datas em **ISO 8601**.
- Cada consulta a `/decision`, `/lookup`, `/identity`, `/kyc`, `/sources` ou `/name` conta 1 requisição para efeito de cota/cobrança. Reports enviados por você são gratuitos.

---

## Endpoints

### POST /api/v1/decision

Manda um identificador e o **seu limite**; a resposta já vem com `APPROVE`, `REVIEW` ou `DENY`.

**Requisição**

```bash
curl -X POST https://compliancefy.com.br/api/v1/decision \
  -H "Authorization: Bearer $CFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "novo.cpf@cliente.com", "ip": "203.0.113.44", "hwid": "DEVICE-9", "denyAbovePercent": 50 }'
```

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `query` | string | sim | E-mail, CPF, CNPJ, telefone ou IP |
| `denyAbovePercent` | 0–100 | não | Nega quando a taxa de fraude ≥ este valor (padrão 50) |
| `reviewAbovePercent` | 0–100 | não | Marca `REVIEW` a partir deste valor |
| `minNetworkSize` | int | não | Mínimo de sinais para poder negar (padrão 1) |
| `ip` | string | não | IP: cruzado com a sua blocklist **e** com o histórico da rede |
| `hwid` | string | não | HWID: cruzado com a sua blocklist **e** com o histórico da rede |

**Resposta `200`**

```json
{
  "query": { "type": "CPF", "value": "44662511500" },
  "found": true,
  "linkedByDevice": true,
  "blocked": false,
  "blockedByYou": false,
  "decision": "DENY",
  "fraudRatePct": 100,
  "complaints": 1,
  "validations": 0,
  "networkSize": 1,
  "reason": "Sinal de fraude vinculado ao IP/HWID (mesmo dispositivo de um caso reportado)."
}
```

**O golpista não escapa trocando de CPF.** Se o `ip` ou o `hwid` já foram reportados junto de um fraudador, a ficha da rede aparece mesmo com um CPF/e-mail novo e limpo — a resposta vem `linkedByDevice: true`. Reporte sempre IP e HWID junto com o fraudador (ver `/reports`).

Se `query`, `ip` ou `hwid` estiverem na sua blocklist, a resposta vem `DENY` com `blockedByYou: true`.

---

### POST /api/v1/lookup

Retorna o score de risco, os identificadores vinculados (mascarados) e os reports da rede.

**Requisição**

```bash
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" }'
```

Opcional: `denyThreshold` (0–1) para receber também um objeto `decision`.

**Resposta `200`**

```json
{
  "query": { "type": "EMAIL", "value": "fraudster@example.com" },
  "found": true,
  "entity": { "id": "…", "type": "PERSON" },
  "risk": {
    "score": 97, "band": "HIGH",
    "totalReports": 8, "complaints": 7, "validations": 1,
    "networkSize": 8, "fraudRate": 0.875, "fraudRatePct": 88,
    "byType": { "CHARGEBACK": 3, "MED": 1, "MULTI_ACCOUNT": 1 },
    "totalAmountCents": 321700
  },
  "identifiers": [ { "type": "EMAIL", "value": "fr*******@example.com" } ],
  "reports": [
    { "id": "…", "type": "CHARGEBACK", "amountCents": 49900, "currency": "BRL",
      "reference": "TX-1001", "reportedBy": "Acme", "occurredAt": "2026-07-09T…" }
  ]
}
```

Sem histórico: `found: false` e `score: 0`. Aceita também `ip` e `hwid` para cruzar o histórico do dispositivo (resposta traz `linkedByDevice`).

---

### POST /api/v1/reports

Registra um evento de compliance sobre uma entidade. Requer escopo `report`.

> **Reporte o IP e o HWID junto com o fraudador.** Todos os identificadores enviados juntos ficam vinculados à mesma entidade. Assim, se o golpista voltar com **outro CPF** mas no **mesmo dispositivo/IP**, o `/decision` o barra pelo histórico da rede (`linkedByDevice: true`).

**Requisição**

```bash
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": "IP", "value": "203.0.113.44" },
      { "type": "HWID", "value": "DEVICE-9" }
    ],
    "type": "CHARGEBACK",
    "amountCents": 49900,
    "reference": "TX-1001"
  }'
```

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `identifiers` | string[] \| obj[] | sim | 1+ identificadores da entidade |
| `type` | enum | sim | Ver "Tipos de sinal" |
| `amountCents` | int | não | Valor em centavos |
| `reference` | string | não | ID externo |
| `description` | string | não | Texto livre |
| `occurredAt` | ISO 8601 | não | Padrão: agora |

Identificadores tipados (para valores opacos):

```json
{ "identifiers": [{ "type": "HWID", "value": "abc123" }], "type": "FRAUD" }
```

**Resposta `201`**

```json
{ "id": "…", "entityId": "…", "type": "CHARGEBACK", "occurredAt": "2026-07-22T…", "createdAt": "2026-07-22T…" }
```

**Observação:** reports do tipo `MED` exigem comprovação e passam pela análise no painel — enviá-los pela API retorna `400` com orientação para usar a página MED do painel.

---

### POST /api/v1/identity

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).

**Requisição**

```bash
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" }'
```

**Resposta `200`**

```json
{
  "query": { "type": "CNPJ", "value": "12345678000199" },
  "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 é best-effort: se a fonte pública não responder, o campo vem `null`.

---

### POST /api/v1/kyc — KYC Transparente

Verificação de identidade real: valida o documento por dígito verificador (CPF/CNPJ), decodifica e valida as **fotos** (documento e selfie), roda triagem PEP e considera o histórico da rede. Envie as imagens em base64 (data URL ou base64 puro).

**Requisição**

```bash
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..."
  }'
```

**Resposta `200`**

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

`status` pode ser `VERIFIED`, `REJECTED` ou `MANUAL_REVIEW` (casos inconclusivos vão para a fila de análise da Compliancefy). Quais checks rodam depende das configurações de KYC da organização. Retorna `409 kyc_disabled` se o KYC estiver desligado.

---

### POST /api/v1/kyc/sessions — KYC Pro hospedado (link / iframe)

Cria uma sessão de KYC hospedada. Abra a `url` (ou embuta via iframe) para o cliente final concluir a verificação — sem construir tela nenhuma.

**Requisição**

```bash
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" }'
```

**Resposta `201`**

```json
{
  "id": "ckyc_…",
  "status": "PENDING",
  "url": "https://compliancefy.com.br/kyc/ckyc_…",
  "embed": "<iframe src=\"https://compliancefy.com.br/kyc/ckyc_…\" allow=\"camera\" style=\"border:0;width:100%;height:640px\"></iframe>"
}
```

Embutido em iframe, a página avisa o site pai via `postMessage`:

```json
{ "source": "compliancefy-kyc", "type": "kyc:done", "verdict": "VERIFIED", "score": 100 }
```

e redireciona para `redirectUrl` ao final.

---

### GET /api/v1/kyc/sessions/{id}

Lê o resultado de uma sessão de KYC hospedada.

```bash
curl https://compliancefy.com.br/api/v1/kyc/sessions/ckyc_… \
  -H "Authorization: Bearer $CFY_KEY"
```

**Resposta `200`**

```json
{
  "id": "ckyc_…",
  "status": "COMPLETED",
  "reference": "pedido-123",
  "createdAt": "2026-07-22T…",
  "completedAt": "2026-07-22T…",
  "result": { "status": "VERIFIED", "score": 100 }
}
```

`status` da sessão: `PENDING` ou `COMPLETED`. Enquanto pendente, `result` é `null`.

---

## Tipos de sinal (`type` em /reports)

| Tipo | Categoria | Polaridade | Peso |
|---|---|---|---|
| `FRAUD` | Pagamento | Reclamação | 40 |
| `MED` | Pagamento | Reclamação | 30 |
| `CHARGEBACK` | Pagamento | Reclamação | 25 |
| `DISPUTE` | Pagamento | Reclamação | 12 |
| `REFUND` | Pagamento | Neutro | 6 |
| `CLONED_DATA` | Identidade | Reclamação | 45 |
| `IDENTITY_MISMATCH` | Identidade | Reclamação | 25 |
| `DOCUMENT_FORGERY` | Identidade | Reclamação | 38 |
| `MULTI_ACCOUNT` | Identidade | Reclamação | 20 |
| `ACCOUNT_TAKEOVER` | Acesso | Reclamação | 40 |
| `SUSPICIOUS_LOGIN` | Acesso | Reclamação | 15 |
| `VALIDATION` | Pagamento | Positivo | 0 |
| `LOGIN_OK` | Acesso | Positivo | 0 |
| `KYC_APPROVED` | KYC | Positivo | 0 |

> `MED` via API é bloqueado: exige comprovação e análise pelo painel.

## Tipos de identificador

`EMAIL`, `CPF`, `CNPJ`, `PHONE`, `IP`, `HWID`. Os cinco primeiros são detectados por formato; `HWID` (e qualquer valor opaco) deve ser enviado tipado.

---

## Erros

Formato: `{ "error": { "code": "...", "message": "..." } }`

| HTTP | code | Quando |
|---|---|---|
| `400` | `bad_request` | Corpo inválido ou identificador irreconhecível |
| `401` | `unauthorized` | API key ausente, inválida ou revogada |
| `403` | `forbidden` | A chave não tem o escopo necessário |
| `409` | `kyc_disabled` | KYC desligado nas configurações da organização |

Exemplo:

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

---

## Integração com IA (dica)

Cole este arquivo inteiro num assistente e use um prompt como:

> "Aqui está a documentação da API da Compliancefy. Gere um cliente em **[sua linguagem/framework]** que:
> 1. leia a API key de uma variável de ambiente `CFY_KEY`;
> 2. antes de aprovar um pagamento, chame `POST /api/v1/decision` e bloqueie se `decision == "DENY"`;
> 3. registre chargebacks em `POST /api/v1/reports`.
> Trate os erros 400/401/403 e inclua exemplos de uso."

---

*Referência da API Compliancefy. Valores e comportamentos refletem a implementação atual. Base: `https://compliancefy.com.br`.*