Objeto Face Database Validation

A validação de um rosto contra a base de rostos da QI Tech deve ser realizada através do endpoint de Event Type Face Database Validation. A API verifica se o rosto enviado já é conhecido pela base de rostos e decide o evento a partir disso.

O fluxo tem duas etapas:

1. Captura do rosto. Gere um registro facial no Reconhecimento Facial, por SDK ou API. O registration_key retornado identifica esse registro.
2. Validação. Envie o registration_key neste Event Type. A API procura o rosto na base de rostos e retorna a decisão.

Escopo do Event Type

O Face Database Validation somente consulta a base de rostos com o registro enviado. A base de rostos e o cadastro de referência do CPF continuam os mesmos após a validação.

Dinâmica dos Status - analysis_status

O status analysis_status indica o status da decisão do motor de fraude. A resposta da requisição é sempre síncrona. Quando o evento é encaminhado para análise manual, a resposta traz in_manual_analysis e o tratamento manual acontece de forma assíncrona: a decisão final é enviada via Webhook. A integração deve tratar os dois cenários.

Status que podem ser retornados na resposta da requisição:

analysis_status	descrição
automatically_approved	Os algoritmos da QI Tech recomendam que este evento seja aprovado.
automatically_reproved	Os algoritmos da QI Tech recomendam que este evento seja reprovado.
automatically_challenge	Os algoritmos da QI Tech recomendam que o usuário tome uma ação para adquirir mais informações para a análise.
in_manual_analysis	Os algoritmos da QI Tech enviaram este evento para a análise manual. A decisão final chega via Webhook.

Status enviados via Webhook, após a análise manual:

analysis_status	descrição
manually_approved	Após análise manual, o analista decidiu aprovar o evento.
manually_reproved	Após análise manual, o analista decidiu reprovar o evento.

A descrição completa da máquina de estados está em Dinâmica dos status.

Definição do Objeto Face Database Validation

Request Body

{
  "id": "e034f932-9729-467f-9fcf-4b60cfbf06e1",
  "event_date": "2026-08-03T11:35:29.777Z",
  "document_number": "045.224.930-96",
  "face": {
    "registration_key": "d8cccd5d-015d-453d-b5ad-3d8c3cb718ea"
  }
}

nome	tipo	descrição
id	string	Identificador do evento no seu sistema, com 1 a 50 caracteres. É essencial que este número seja único para cada requisição (obrigatório)
event_date	datetime	Data e hora em que o evento ocorreu na sua aplicação, em ISO 8601 com fuso horário. Aceita offset explícito (-03:00) ou UTC (Z). Não aceita data sem fuso horário. (obrigatório)
document_number	string	CPF do titular com pontuação, no formato XXX.XXX.XXX-XX. (obrigatório)
face	face	Objeto com o registro facial a ser procurado na base de rostos. (obrigatório)
face.registration_key	string	Identificador (UUID) do registro facial gerado no Reconhecimento Facial, por SDK ou API. É o rosto que será procurado na base de rostos. (obrigatório)

Enviar um Face Database Validation

Request Body

  {
    "id": "e034f932-9729-467f-9fcf-4b60cfbf06e1",
    ...
  }

Response Body - automatically_approved

  {
    "id": "e034f932-9729-467f-9fcf-4b60cfbf06e1",
    "analysis_status": "automatically_approved",
    "reason": "Identidade validada automaticamente",
    "reason_description": "Identidade validada automaticamente"
  }

Response Body - automatically_reproved

  {
    "id": "8daca5f4-e109-4ccc-8522-12358702d04d",
    "analysis_status": "automatically_reproved",
    "reason": "Não há indícios suficientes para constatarmos que a foto enviada pertence ao titular do documento",
    "reason_description": "Não há indícios suficientes para constatarmos que a foto enviada pertence ao titular do documento"
  }

Para realizar a validação, basta enviar um objeto do tipo Face Database Validation ao seguinte endpoint:

POST https://api.caas.qitech.app/account_event/event_type/face_database_validation/event

A resposta possui os seguintes campos:

nome	tipo	descrição
id	string	Mesmo id enviado na requisição, ecoado para correlação.
analysis_status	enumerador	Decisão da análise para o evento. É o campo em que a integração deve ramificar.
reason	string	Motivo que determinou a decisão. Os valores são definidos na configuração de cada cliente, portanto variam por integração e por Event Type.
reason_description	string	Descrição legível do motivo, para exibição em telas operacionais e trilha de auditoria.

Um mesmo request pode resultar em qualquer um dos status, conforme a configuração da integração e o que a base devolve:

analysis_status	leitura	ação esperada na jornada
automatically_approved	Identidade validada automaticamente na base de rostos.	Seguir a jornada. Nenhuma ação adicional.
automatically_reproved	Não há indícios suficientes de que a foto enviada pertença ao titular do documento.	Bloquear a etapa e aplicar a política de recusa combinada. Reenvio só com nova captura.

Ramifique pelo analysis_status

Os valores de reason são definidos na configuração de cada cliente. Não construa lógica sobre o texto do reason: use-o para exibição e auditoria, e ramifique pelo analysis_status.