> For the complete documentation index, see [llms.txt](https://docs.griaule.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.griaule.com/integracao-do-gbds/fluxos-de-notificacao-gbds-5.md).

# Fluxos de Notificação GBDS 5

Quando o GBDS realiza operações de cadastro (enroll), atualização (update), remoção (delete) e tratamento de exceções, notificações são enviadas para endpoints designados para informar seus resultados. A entidade responsável por este fluxo é chamada Notificador.

Este documento descreve os fluxos de notificação durante operações de cadastro, atualização, remoção e tratamento de exceções.

{% hint style="info" %}
Para informações adicionais sobre fluxos de notificação durante controle de sequência e controle de qualidade, consulte a documentação de [controle de sequência e controle de qualidade](https://docs.griaule.com/integracao-do-gbds/qualitycontrol.md).
{% endhint %}

{% hint style="info" %}
Todas as notificações enviadas pelo Notificador são HTTP POST para um endpoint configurado (`http://<endereço>:<porta>`), contendo um objeto JSON. O modelo do JSON para cada notificação está apresentado abaixo.
{% endhint %}

{% hint style="warning" %}
O endpoint que receberá a notificação **deve ser implementado individualmente** para cada sistema.
{% endhint %}

### Transação Aceita

Todas as transações assíncronas recebidas serão enfileiradas. Após o processamento, uma notificação é enviada informando que a operação foi concluída.

A mensagem de notificação será como no exemplo abaixo:

```json
{
	"operation": "<operação>",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}
```

{% hint style="info" %}
As possíveis operações neste passo são: `ENROLL` (usada tanto para cadastro quanto para atualização) e `SEARCH`.
{% endhint %}

O notificador pode retornar status diferentes, conforme o tipo de transação sendo realizada. Os possíveis status **finais** são:

| Operação      | Status                                             |
| ------------- | -------------------------------------------------- |
| Enroll/Update | `ENROLLED`, `FAILED`                               |
| Search        | `MATCH`, `NOT_MATCH`, `FAILED`, `PERSON_NOT_FOUND` |

O status `FAILED` ocorre sempre que uma transação for abortada ou não puder ser finalizada.

O status `PERSON_NOT_FOUND` ocorre quando uma busca 1:1 é recebida, mas o perfil de referência não existe para a chave fornecida.

#### Campos adicionais da notificação de `ENROLL`

A notificação de operação `ENROLL` pode trazer campos adicionais, dependendo do contexto da transação:

| Campo                                | Quando aparece                                                                                                                                                       |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pguid`                              | Sempre que há um pguid de referência associado à transação                                                                                                           |
| `update`                             | Indica se a transação é uma atualização (`true`/`false`)                                                                                                             |
| `trusted`                            | Indica se a transação é uma transação confiável (trusted master record)                                                                                              |
| `treatment`                          | Valor `BoB` quando a transação resultou de um "Best of Biometrics"                                                                                                   |
| `exceptionGroupTguid`                | Presente quando a transação está associada a um grupo de exceção (ex: transação nova gerada por um tratamento de grupo, ou transação rejeitada durante o tratamento) |
| `originalRefusedTguid`               | Presente quando a transação é o reenvio de uma transação previamente recusada (`REFUSED`)                                                                            |
| `externalIDs` / `relatedExternalIDs` | IDs externos da transação e IDs externos relacionados (herdados de transações anteriores)                                                                            |
| `removedKeys`                        | Chaves removidas por inconsistência, com o motivo, quando aplicável                                                                                                  |
| `originalInconsistentKeys`           | Chaves originais consideradas inconsistentes, quando aplicável                                                                                                       |
| `newTransactionGUID`                 | Presente em notificações de falha/rejeição, quando há uma nova transação substituta                                                                                  |
| `gguid`                              | Presente quando a notificação está associada a um grupo de exceção                                                                                                   |

Exemplo de notificação `ENROLL` com campos adicionais:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED",
	"pguid": "<pguid>",
	"update": false,
	"trusted": true,
	"treatment": "BoB",
	"exceptionGroupTguid": "<gguid-relacionado>",
	"externalIDs": [{ "name": "<nome>", "key": "<valor>" }],
	"relatedExternalIDs": [{ "name": "<nome>", "key": "<valor>" }]
}
```

### Transação Enviada para Revisão Manual

Nos casos em que o GBDS identificou problemas relacionados ao controle de sequência ou controle de qualidade, e a transação foi enviada para revisão manual, uma notificação será enviada indicando que o cadastro está pendente, como no exemplo abaixo:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "PENDING"
}
```

{% hint style="info" %}
Consulte o Manual do MIR (Manual Image Review) para maiores detalhes sobre resolução de transações enviadas para revisão manual.
{% endhint %}

Após a análise no MIR, o servidor processa a decisão do examinador e envia as notificações correspondentes, conforme descrito abaixo.

{% stepper %}
{% step %}

#### Transação Aprovada Sem Mudanças

Dada essa decisão, o GBDS manterá a transação original sem mudanças e continuará o processo de cadastro. O TGUID (Global Unique IDentifier da transação) permanecerá o mesmo para ambas as operações (`QUALITY_ANALYSIS` e `ENROLL`).

A primeira notificação conterá o status `APPROVED` para a operação `QUALITY_ANALYSIS`:

```json
{
	"operation": "QUALITY_ANALYSIS",
	"tguid": "<tguid>",
	"status": "APPROVED"
}
```

A segunda notificação conterá o status `ENROLLED` para a operação `ENROLL`:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}
```

{% endstep %}

{% step %}

#### Transação Aprovada com Mudanças

Dada essa decisão, o GBDS manterá as mudanças feitas pelo examinador (imagens deletadas ou editadas) e gerará um novo TGUID para o cadastro.

O fluxo de notificação é similar ao da "Transação Aprovada Sem Mudanças", com a adição do novo TGUID. A primeira notificação conterá o status `APPROVED` para a operação `QUALITY_ANALYSIS` e incluirá o campo `newTransactionGUID`, apontando para o novo TGUID:

```json
{
	"newTransactionGUID": "<new_tguid>",
	"operation": "QUALITY_ANALYSIS",
	"tguid": "<original_tguid>",
	"status": "APPROVED"
}
```

A segunda notificação conterá o status `ENROLLED` para a operação `ENROLL`:

{% hint style="info" %}
A operação `ENROLL` será realizada para a transação alterada, então o TGUID mencionado será o novo TGUID gerado pela operação `QUALITY_ANALYSIS`.
{% endhint %}

```json
{
	"operation": "ENROLL",
	"tguid": "<new_tguid>",
	"status": "ENROLLED"
}
```

{% endstep %}

{% step %}

#### Transação Rejeitada

Dada essa decisão, o GBDS não continuará o processo de cadastro e descartará toda a transação. O TGUID continuará o mesmo.

{% hint style="info" %}
O histórico da transação será mantido, mas o perfil não será inserido no banco de dados como um registro de pessoa ativa.
{% endhint %}

A primeira notificação conterá o status `REJECTED` para a operação `QUALITY_ANALYSIS`:

```json
{
	"operation": "QUALITY_ANALYSIS",
	"tguid": "<tguid>",
	"status": "REJECTED"
}
```

O resultado da operação `QUALITY_ANALYSIS` será seguido de uma notificação de cadastro com status `FAILED` para a operação `ENROLL`:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "FAILED"
}
```

{% endstep %}
{% endstepper %}

### Transação com Exceção Biométrica

Se uma exceção for gerada ao processar a transação, a transação entrante será enviada ao tratamento de exceções para análise. Neste caso, a notificação é enviada informando que a transação causou uma exceção, como mostrado no exemplo abaixo:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "EXCEPTION"
}
```

{% hint style="info" %}
Notificações geradas por operações de Atualização (Update) não alteram o campo `operation`, e a seção `"operation": "ENROLL"` será igual para operações de cadastro e atualização.
{% endhint %}

{% hint style="info" %}
Consulte o Manual do Trust para maiores detalhes sobre tratamento de exceções.
{% endhint %}

#### Tratamento de Exceção por Grupo (Trust)

O tratamento de exceções é feito em nível de **grupo de exceções**, através do Trust. Ao final do tratamento de um grupo, uma notificação de operação `TREAT_EXCEPTION_GROUP` é enviada, seguida — quando aplicável — pelas notificações de `ENROLL` refletindo o resultado final da(s) transação(ões) envolvida(s): cadastro efetivado, atualização efetivada, ou falha/rejeição.

Exemplo de notificação de tratamento de grupo:

```json
{
	"operation": "TREAT_EXCEPTION_GROUP",
	"tguid": "<tguid>",
	"status": "<target>-<decision>",
	"target": "<target>",
	"gguid": "<gguid>",
	"treatment": "<decisão do grupo>",
	"subDecision": "<detalhe do sub-fluxo>",
	"newTransactionGUID": "<nova tguid, se houver>",
	"pguid": "<novo pguid, se houver>",
	"keptTguids": ["<tguid mantida 1>", "<tguid mantida 2>"]
}
```

| Campo                | Descrição                                                                                                            |
| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `target`             | Alvo da exceção do grupo (ex: biométrico, biográfico)                                                                |
| `gguid`              | Identificador do grupo de exceção                                                                                    |
| `treatment`          | Decisão tomada para o grupo                                                                                          |
| `subDecision`        | Detalha o sub-fluxo do tratamento (ex: `ENROLL`, `UPDATE_ENTRANT`, `UPDATE_REFERENCE`, `UPDATE_BOTH`, `UPDATE_NONE`) |
| `newTransactionGUID` | Presente quando o tratamento gera uma nova transação (enroll confiável ou reenvio)                                   |
| `pguid`              | pguid da nova transação, quando aplicável                                                                            |
| `keptTguids`         | Lista de tguids mantidas no tratamento, quando a decisão é de manutenção                                             |

Transações rejeitadas ou descartadas durante o tratamento de grupo geram notificações de `ENROLL` com `status: FAILED`, incluindo o `gguid` do grupo e, quando houver, a `newTransactionGUID`:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid rejeitada>",
	"status": "FAILED",
	"gguid": "<gguid>",
	"newTransactionGUID": "<nova tguid, se houver>",
	"exceptionGroupTguid": "<gguid>"
}
```

### Casamento com Latente Não Resolvida

Ao realizar uma busca contra uma base de latentes não resolvidas, quaisquer casamentos encontrados gerarão notificações de casamento reverso de latente (Reverse latent match), contendo o UGUID da latente não resolvida (UL, Unsolved Latent) casada. A transação de cadastro ou atualização prosseguirá normalmente, sendo comparada com a base referência. Esta busca normal pode resultar em conclusão normal ou gerar exceção. O exemplo abaixo mostra as notificações recebidas em uma situação de casamento de latente não resolvida seguida de cadastro bem-sucedido:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "REVERSE_LATENT_MATCH",
	"uguid": "<uguid>"
}
```

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}
```

### Reenvio de Transação Recusada

Quando uma transação recusada (`REFUSED`) é reenviada automaticamente pelo GBDS, uma notificação é enviada informando o reenvio, com a nova tguid vinculada:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid original>",
	"status": "RESENT_ENROLL",
	"newTransactionGUID": "<nova tguid>"
}
```

### Remoção

Ao final do processo de remoção de uma pessoa ou de uma biometria no GBDS, uma notificação é enviada informando o resultado da operação:

```json
{
	"operation": "DELETE",
	"tguid": "<tguid da tarefa>",
	"status": "COMPLETED",
	"pguid": "<pguid>",
	"relatedExternalIDs": [{ "name": "<nome>", "key": "<valor>" }]
}
```

O status `COMPLETED` é enviado tanto para remoção de biometria quanto de pessoa, ao final da execução da tarefa.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.griaule.com/integracao-do-gbds/fluxos-de-notificacao-gbds-5.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
