Objeto Registration Data Validation

A validação de um dado cadastral de um cliente já existente deve ser realizada através do endpoint de Event Type Registration Data Validation. Na configuração descrita aqui o dado validado é o rosto: a API verifica se o rosto enviado corresponde ao rosto já cadastrado anteriormente para aquele CPF.

O fluxo tem duas etapas:

1. Cadastro do rosto. O rosto do titular precisa ter sido registrado previamente na API de Reconhecimento Facial, através da Criação de um registro (POST). Esse é o registro de referência do CPF.
2. Validação. Em um ponto posterior da jornada, gere um novo registro facial (por SDK ou API) e envie o registration_key dele neste Event Type. A API compara esse novo registro com o rosto cadastrado na etapa 1.

Escopo do Event Type

O Registration Data Validation somente compara o rosto enviado com o rosto já cadastrado para o CPF. O cadastro de referência continua o mesmo após a validação e é gerenciado exclusivamente pela API de Registro de rosto.

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 Registration Data Validation

Request Body

{
  "id": "ce219137-b7f6-48a5-9b9b-0f1f15ddbf5b",
  "event_date": "2026-07-31T16:01:56.515Z",
  "document_number": "430.684.374-23",
  "face": {
    "registration_key": "bc138845-a0e6-4cb4-a6f6-e3f567baa0f0"
  }
}

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. É a chave pela qual o registro facial da base é consultado. (obrigatório)
face	face	Objeto com o registro facial a ser comparado com o rosto registrado para o CPF. (obrigatório)
face.registration_key	string	Identificador (UUID) do novo registro facial gerado no Reconhecimento Facial, por SDK ou API. É o rosto que será comparado com o registro cadastrado anteriormente para o CPF, e não o registration_key desse cadastro. (obrigatório)

Enviar um Registration Data Validation

Request Body

  {
    "id": "ce219137-b7f6-48a5-9b9b-0f1f15ddbf5b",
    ...
  }

Response Body - automatically_approved

  {
    "id": "ce219137-b7f6-48a5-9b9b-0f1f15ddbf5b",
    "analysis_status": "automatically_approved",
    "reason": "rosto_deu_match",
    "reason_description": "Rosto deu match"
  }

Response Body - automatically_reproved

  {
    "id": "ce219137-b7f6-48a5-9b9b-0f1f15ddbf5b",
    "analysis_status": "automatically_reproved",
    "reason": "rosto_nao_deu_match",
    "reason_description": "Rosto não deu match"
  }

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

POST https://api.caas.qitech.app/account_event/event_type/registration_data_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 resultado da comparação:

analysis_status	leitura	ação esperada na jornada
automatically_approved	O rosto enviado é compatível com o rosto cadastrado para o CPF.	Seguir a jornada. Nenhuma ação adicional.
automatically_reproved	O rosto enviado não é compatível com o rosto cadastrado para o CPF.	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.