> ## Documentation Index
> Fetch the complete documentation index at: https://documentacao.legitimuz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Score

> Os dois scores de uma verificação, as catorze regras que os formam e como usá-los sem transformá-los na decisão.

Toda verificação recebe dois números independentes: um de risco e um de identidade. Eles resumem o
que as regras encontraram na jornada.

<Info>
  O score está em implementação. As regras e os números abaixo são o contrato acordado; a entrega
  do bloco `score` no webhook ainda não está disponível em produção.
</Info>

## Os dois eixos

| No dashboard            | Na API           | O que mede                                                                                | Leitura              |
| ----------------------- | ---------------- | ----------------------------------------------------------------------------------------- | -------------------- |
| **Score de Fraude**     | `risk_score`     | sinais de fraude em volta da jornada: device, rede, reincidência, listas                  | quanto maior, pior   |
| **Score de Identidade** | `identity_score` | quanto a identidade se sustenta: prova de vida, documento, facematch, coerência cadastral | quanto maior, melhor |

Ambos vão de 0 a 100.

São eixos separados de propósito. Uma jornada pode ter identidade sólida e risco alto, a pessoa é
quem diz ser, e mesmo assim o padrão de uso pede atenção. Um número só esconderia isso.

<Warning>
  O score é sinal para a sua decisão, não a decisão. Ele não substitui o `status` da verificação, e
  nenhum corte de score deve ser o único critério de uma recusa que afete a pessoa.
</Warning>

## As regras

Catorze regras, agrupadas por eixo. Cada uma devolve um estado, um motivo em código e quantos pontos
somou.

### Identidade

| `rule_key`                                 | O que procura                                   |
| ------------------------------------------ | ----------------------------------------------- |
| `identity:liveness_rejected`               | a prova de vida foi recusada                    |
| `identity:facematch_rejected`              | o rosto da selfie não bate com o do documento   |
| `identity:documentoscopy_rejected`         | a análise do documento recusou a peça           |
| `identity:biometric_search_low_confidence` | a busca biométrica voltou com confiança baixa   |
| `identity:age_mismatch`                    | a idade do documento diverge da base cadastral  |
| `identity:gender_mismatch`                 | o gênero do documento diverge da base cadastral |

### Risco

| `rule_key`                                | O que procura                                         |
| ----------------------------------------- | ----------------------------------------------------- |
| `risk:proxy_or_vpn`                       | a jornada veio por proxy ou VPN                       |
| `risk:device_manipulation`                | sinais de emulador, root, jailbreak ou instrumentação |
| `risk:same_device_other_cpf`              | o mesmo aparelho já apareceu com outros CPFs          |
| `risk:same_face_other_cpf`                | o mesmo rosto já apareceu com outros CPFs             |
| `risk:different_face_same_cpf`            | rostos diferentes para o mesmo CPF                    |
| `risk:device_changed_same_cpf`            | o CPF trocou de aparelho                              |
| `risk:baseline_location_or_device_change` | localização ou aparelho mudou em relação ao histórico |
| `risk:internal_blacklist_match`           | o titular bateu com a lista interna                   |

## Ler uma regra

Na aba **Composição de Score** de uma [verificação](/platform/verifications), os sinais aparecem
agrupados em **Biometria**, **Dispositivo** e **Rede & Localização**, cada um com um desfecho:
**Limpo**, **Atenção** ou **Alerta**.

No webhook, a mesma informação chega estruturada:

| Campo          | O que é                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------- |
| `rule_key`     | `categoria:nome`, o identificador estável da regra                                             |
| `rule_version` | a versão da regra que produziu o resultado                                                     |
| `status`       | `MATCHED` · `NOT_MATCHED` · `INSUFFICIENT_DATA` · `NOT_APPLICABLE` · `ERROR` · `NOT_EVALUATED` |
| `reason_code`  | o motivo em código estável, use este na sua lógica                                             |
| `score_points` | quanto somou, por eixo                                                                         |
| `evaluated_at` | quando a regra rodou                                                                           |
| `details`      | contexto da avaliação, variável por regra                                                      |

<Warning>
  `MATCHED` significa que a regra **encontrou** o que procura, ou seja, um sinal **contra** a
  jornada. E `INSUFFICIENT_DATA` não é aprovação: a regra não teve o que avaliar. Um fluxo sem etapa
  de device nunca pontua as regras de device.
</Warning>

## Usar no seu backend

Leia o estado das regras, não só os números. Duas jornadas com o mesmo `risk_score` por motivos
diferentes pedem tratamentos diferentes.

```ts title="Separar os sinais que importam" theme={null}
type RegraDeScore = {
  rule_key: string;
  status: "MATCHED" | "NOT_MATCHED" | "INSUFFICIENT_DATA" | "NOT_APPLICABLE" | "ERROR" | "NOT_EVALUATED";
  reason_code: string;
  score_points: { risk?: number; identity?: number };
};

function sinaisContra(breakdown: Record<string, RegraDeScore>): string[] {
  return Object.values(breakdown)
    .filter((regra) => regra.status === "MATCHED")
    .map((regra) => regra.reason_code);
}
```

<Card title="verification.scored" icon="webhook" href="/webhooks/events#verificationscored" horizontal>
  O contrato completo do evento, com o corpo e o breakdown.
</Card>

## Próximo passo

<Card title="9. Fluxos" icon="git-branch" href="/platform/flows" horizontal>
  As etapas que alimentam as regras de score.
</Card>