Ler a resposta

Tudo o que vem a seguir é diagnóstico. A decisão já foi tomada com status e spoofing; esta página serve para entender o que aconteceu, alimentar os seus logs e abrir chamados com contexto.

Campos da resposta

Campo	Tipo	Para que serve
`spoofing`	boolean	O veredito. `false` com `200` é a única aprovação.
`id`	string	Identificador único da transação. Registre-o sempre.
`code`	number	Espelho do código HTTP.
`message`	string	Texto legível do resultado. Útil no log, não para decidir.
`info`	objeto \| string \| null	Sua referência e, quando existe, o diagnóstico. Veja abaixo.
`date` / `time`	string	Momento da análise do lado do serviço.
`values`	objeto	Pontuações internas do modelo (`FAKE`, `REAL`). Diagnóstico.
`confidence`	number	Confiança do componente que respondeu. Veja o aviso sobre escalas.
`imageQuality`	objeto	Mapa opcional de indicadores de qualidade. Veja abaixo.
`benchmark`	number	Milissegundos que a análise levou.
`errorCode` / `errorMessage`	number / string	Detalhe interno. Diagnóstico.

Não construa lógica de negócio sobre errorCode, values, confidence ou info. Não fazem parte do contrato e sua forma muda entre versões do serviço.

`info`: três formas, um único leitor

info é polimórfico. Pode chegar como objeto, como string ou como null — e null aparece em dois lugares distintos: o info de nível superior e o info.info aninhado.

{
  "info": {
    "info": "onboarding-12345",
    "mode": "active",
    "service": "as-face",
    "user": "userName",
    "deepfake-filter": { "provider": "A", "detected": false, "confidence": 99 }
  }
}

{
  "info": "onboarding-12345"
}

{
  "info": null
}

function referencia(body) {
  const i = body?.info;
  return i == null             ? null
       : typeof i === "string" ? i
       : i.info ?? null;
}

info chegar como objeto não significa que a pessoa foi bloqueada. No nosso banco de testes, as 47 aprovações traziam info como objeto, com deepfake-filter e detected: false — ou seja, o filtro rodou e não encontrou nada. O único campo que separa aprovar de não aprovar é spoofing.

`imageQuality` é opcional, e suas chaves também

imageQuality é um mapa de chaves opcionais: pode faltar por inteiro e, quando está presente, pode trazer algumas chaves e outras não. Em 116 respostas de teste, 102 traziam face, 10 traziam brightSpots e as 4 respostas 422 No Face Detected não traziam imageQuality de forma alguma — coerente: sem rosto, não há o que medir.

"imageQuality": {
  "blurry": false,
  "underExposure": false,
  "overExposure": false,
  "borderDetected": false,
  "face": {
    "is_centered_x": true,
    "is_centered_y": true,
    "is_close_to_borders": false,
    "is_too_small": false,
    "is_too_large": false
  }
}

Leia cada nível de forma defensiva. body.imageQuality?.face?.is_too_small está correto; body.imageQuality.face.is_too_small lança exceção no dia em que chegar um 422.

Qual componente respondeu

Quando info é um objeto, suas chaves revelam o que o serviço detectou. Esta tabela serve para ler um caso, não para decidir sobre ele:

Situação	Sinais em `info`	`imageQuality` típico
Análise limpa	`deepfake-filter` com `detected: false`, mais `mode`	`face`
Marca d’água ou texto sobreposto	`text` e `matches[]`	`brightSpots`
Alteração cromática («pessoas azuis»)	`blue-filter`	`brightSpots`
Deepfake detectado — provedor A	`deepfake-filter` com `detected: true`	`brightSpots`
Deepfake ou conteúdo gerado por IA — provedor B	`deepfake-filter` com `detected: true`	`brightSpots`
Fotocópia	Texto em `info` ou `null`	`face`
Captura de tela	Texto em `info` ou `null`	`face`
Borda de outra tela no quadro	`borderDetected: true`	`face`

Nunca escreva lógica sobre o valor de info.service. Os nomes internos de serviço mudam. Se precisar saber se houve diagnóstico, pergunte pela presença, não pelo conteúdo.

Os valores de confiança não são comparáveis

Este é o erro de interpretação mais frequente. Na resposta convivem vários números chamados «confiança» com escalas diferentes, e dois deles apontam em direções opostas:

Valor	Escala	O que mede	Ao detectar
`deepfake-filter.confidence` (provedor A)	0–100	Probabilidade de ser autêntica	Cai para `0`
`deepfake-filter.confidence` (provedor B)	0–1	Probabilidade de ser falsa	Sobe para `0.99`
`blue-filter.confidence`	0–100	Intensidade da alteração cromática	—
`matches[].score`	0–100	Similaridade do texto encontrado com a lista de referência	—

Nunca compare, calcule média nem aplique um limiar comum a esses valores. Um confidence: 0 pode significar «certeza absoluta de fraude» (provedor A) e um confidence: 0.99 também (provedor B). Qualquer regra do tipo «se a confiança for maior que X» produz decisões invertidas conforme o componente que respondeu.

Erros

Códigos de erro, como distinguir os seus dos do serviço e quais podem ser repetidos.

Comece aqui

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

Campos da resposta

`info`: três formas, um único leitor

`imageQuality` é opcional, e suas chaves também

Qual componente respondeu

Os valores de confiança não são comparáveis

Erros

​Campos da resposta

​info: três formas, um único leitor

​imageQuality é opcional, e suas chaves também

​Qual componente respondeu

​Os valores de confiança não são comparáveis

Erros

Campos da resposta

`info`: três formas, um único leitor

`imageQuality` é opcional, e suas chaves também

Qual componente respondeu

Os valores de confiança não são comparáveis