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:
- 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.
- Validação. Em um ponto posterior da jornada, gere um novo registro facial (por SDK ou API) e envie o
registration_keydele neste Event Type. A API compara esse novo registro com o rosto cadastrado na etapa 1.
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. |
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.