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.

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.

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.

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.

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, 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

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.

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.

Separar os sinais que importam

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);
}

verification.scored

O contrato completo do evento, com o corpo e o breakdown.

Próximo passo

9. Fluxos

As etapas que alimentam as regras de score.