> 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/gbs/es/integracion-del-gbds/flujos-de-notificacion-de-gbds-5.md).

# Flujos de notificación de GBDS 5

Cuando GBDS realiza operaciones de registro (enroll), actualización (update), eliminación (delete) y gestión de excepciones, se envían notificaciones a los endpoints designados para informar de sus resultados. La entidad responsable de este flujo se denomina Notificador.

Este documento describe los flujos de notificación durante las operaciones de registro, actualización, eliminación y gestión de excepciones.

{% hint style="info" %}
Para obtener más información sobre los flujos de notificación durante el control de secuencia y el control de calidad, consulte la documentación de [control de secuencia y control de calidad](https://docs.griaule.com/gbs/es/integracion-del-gbds/qualitycontrol.md).
{% endhint %}

{% hint style="info" %}
Todas las notificaciones enviadas por el Notificador son solicitudes HTTP POST a un endpoint configurado (`http://<endereço>:<porta>`), que contienen un objeto JSON. A continuación se muestra el modelo JSON de cada notificación.
{% endhint %}

{% hint style="warning" %}
El endpoint que recibirá la notificación **debe implementarse individualmente** para cada sistema.
{% endhint %}

### Transacción aceptada

Todas las transacciones asíncronas recibidas se encolarán. Una vez procesadas, se envía una notificación para informar de que la operación ha finalizado.

El mensaje de notificación tendrá el siguiente formato:

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

{% hint style="info" %}
Las operaciones posibles en este paso son: `ENROLL` (se usa tanto para el registro como para la actualización) y `SEARCH`.
{% endhint %}

El notificador puede devolver distintos estados, según el tipo de transacción que se esté realizando. Los posibles estados **finales** son:

| Operación     | Estado                                             |
| ------------- | -------------------------------------------------- |
| Enroll/Update | `ENROLLED`, `FAILED`                               |
| Search        | `MATCH`, `NOT_MATCH`, `FAILED`, `PERSON_NOT_FOUND` |

El estado `FAILED` se produce siempre que una transacción se aborta o no puede finalizarse.

El estado `PERSON_NOT_FOUND` se produce cuando se recibe una búsqueda 1:1, pero no existe un perfil de referencia para la clave proporcionada.

#### Campos adicionales de la notificación de `ENROLL`

La notificación de la operación `ENROLL` puede incluir campos adicionales, según el contexto de la transacción:

| Campo                                | Cuándo aparece                                                                                                                                                                                      |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pguid`                              | Siempre que haya un pguid de referencia asociado a la transacción                                                                                                                                   |
| `update`                             | Indica si la transacción es una actualización (`true`/`false`)                                                                                                                                      |
| `trusted`                            | Indica si la transacción es una transacción de confianza (registro maestro de confianza)                                                                                                            |
| `treatment`                          | Valor `BoB` cuando la transacción se generó a partir de un "Best of Biometrics"                                                                                                                     |
| `exceptionGroupTguid`                | Está presente cuando la transacción está asociada a un grupo de excepciones (p. ej., una transacción nueva generada por un tratamiento de grupo o una transacción rechazada durante el tratamiento) |
| `originalRefusedTguid`               | Está presente cuando la transacción es el reenvío de una transacción rechazada anteriormente (`REFUSED`)                                                                                            |
| `externalIDs` / `relatedExternalIDs` | IDs externos de la transacción e IDs externos relacionados (heredados de transacciones anteriores)                                                                                                  |
| `removedKeys`                        | Claves eliminadas por inconsistencia, con el motivo, cuando corresponda                                                                                                                             |
| `originalInconsistentKeys`           | Claves originales consideradas inconsistentes, cuando corresponda                                                                                                                                   |
| `newTransactionGUID`                 | Está presente en las notificaciones de fallo/rechazo cuando hay una nueva transacción sustituta                                                                                                     |
| `gguid`                              | Está presente cuando la notificación está asociada a un grupo de excepciones                                                                                                                        |

Ejemplo de notificación `ENROLL` con campos adicionales:

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

### Transacción enviada a revisión manual

En los casos en que GBDS identificó problemas relacionados con el control de secuencia o el control de calidad y la transacción se envió a revisión manual, se enviará una notificación indicando que el registro está pendiente, como en el ejemplo siguiente:

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

{% hint style="info" %}
Consulte el Manual de MIR (Manual Image Review) para obtener más detalles sobre la resolución de transacciones enviadas a revisión manual.
{% endhint %}

Tras el análisis en MIR, el servidor procesa la decisión del examinador y envía las notificaciones correspondientes, tal como se describe a continuación.

{% stepper %}
{% step %}

#### Transacción aprobada sin cambios

Ante esta decisión, GBDS mantendrá la transacción original sin cambios y continuará el proceso de registro. El TGUID (identificador único global de la transacción) seguirá siendo el mismo para ambas operaciones (`QUALITY_ANALYSIS` y `ENROLL`).

La primera notificación contendrá el estado `APPROVED` para la operación `QUALITY_ANALYSIS`:

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

La segunda notificación contendrá el estado `ENROLLED` para la operación `ENROLL`:

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

{% endstep %}

{% step %}

#### Transacción aprobada con cambios

Dada esta decisión, GBDS conservará los cambios realizados por el examinador (imágenes eliminadas o editadas) y generará un nuevo TGUID para el registro.

El flujo de notificaciones es similar al de la «Transacción aprobada sin cambios», con la adición del nuevo TGUID. La primera notificación contendrá el estado `APPROVED` para la operación `QUALITY_ANALYSIS` e incluirá el campo `newTransactionGUID`, que apunta al nuevo TGUID:

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

La segunda notificación contendrá el estado `ENROLLED` para la operación `ENROLL`:

{% hint style="info" %}
La operación `ENROLL` se realizará para la transacción modificada, por lo que el TGUID mencionado será el nuevo TGUID generado por la operación `QUALITY_ANALYSIS`.
{% endhint %}

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

{% endstep %}

{% step %}

#### Transacción rechazada

Dada esta decisión, GBDS no continuará el proceso de registro y descartará toda la transacción. El TGUID seguirá siendo el mismo.

{% hint style="info" %}
Se conservará el historial de la transacción, pero el perfil no se insertará en la base de datos como un registro de persona activa.
{% endhint %}

La primera notificación contendrá el estado `REJECTED` para la operación `QUALITY_ANALYSIS`:

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

El resultado de la operación `QUALITY_ANALYSIS` irá seguido de una notificación de registro con el estado `FAILED` para la operación `ENROLL`:

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

{% endstep %}
{% endstepper %}

### Transacción con excepción biométrica

Si se genera una excepción al procesar la transacción, la transacción entrante se enviará al proceso de gestión de excepciones para su análisis. En este caso, se enviará una notificación para informar que la transacción causó una excepción, como se muestra en el siguiente ejemplo:

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

{% hint style="info" %}
Las notificaciones generadas por operaciones de actualización (Update) no modifican el campo `operation`, y la sección `"operation": "ENROLL"` será la misma para las operaciones de registro y actualización.
{% endhint %}

{% hint style="info" %}
Consulte el Manual de Trust para obtener más detalles sobre la gestión de excepciones.
{% endhint %}

#### Gestión de excepciones por grupo (Trust)

La gestión de excepciones se realiza a nivel de **grupo de excepciones**, a través de Trust. Al finalizar la gestión de un grupo, se envía una notificación de operación `TREAT_EXCEPTION_GROUP` se envía, seguida — cuando corresponda — por las notificaciones de `ENROLL` que reflejan el resultado final de la(s) transacción(es) involucrada(s): registro completado, actualización completada o fallo/rechazo.

Ejemplo de notificación de tratamiento de grupo:

```json
{
	"operation": "TREAT_EXCEPTION_GROUP",
	"tguid": "<tguid>",
	"status": "<target>-<decision>",
	"target": "<target>",
	"gguid": "<gguid>",
	"treatment": "<decisión del grupo>",
	"subDecision": "<detalle del subflujo>",
	"newTransactionGUID": "<nuevo tguid, si lo hay>",
	"pguid": "<nuevo pguid, si lo hay>",
	"keptTguids": ["<tguid conservado 1>", "<tguid conservado 2>"]
}
```

| Campo                | Descripción                                                                                                                |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `target`             | Objetivo de la excepción del grupo (p. ej., biométrico, biográfico)                                                        |
| `gguid`              | Identificador del grupo de excepción                                                                                       |
| `treatment`          | Decisión tomada para el grupo                                                                                              |
| `subDecision`        | Detalla el subflujo del tratamiento (p. ej.: `ENROLL`, `UPDATE_ENTRANT`, `UPDATE_REFERENCE`, `UPDATE_BOTH`, `UPDATE_NONE`) |
| `newTransactionGUID` | Está presente cuando el tratamiento genera una nueva transacción (registro confiable o reenvío)                            |
| `pguid`              | pguid de la nueva transacción, cuando corresponda                                                                          |
| `keptTguids`         | Lista de tguids conservados durante el tratamiento, cuando la decisión es conservarlos                                     |

Las transacciones rechazadas o descartadas durante el tratamiento de grupo generan notificaciones de `ENROLL` con `status: FAILED`, incluido el `gguid` del grupo y, cuando exista, el `newTransactionGUID`:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid rechazado>",
	"status": "FAILED",
	"gguid": "<gguid>",
	"newTransactionGUID": "<nuevo tguid, si lo hay>",
	"exceptionGroupTguid": "<gguid>"
}
```

### Coincidencia con una latente no resuelta

Al realizar una búsqueda en una base de latentes no resueltas, cualquier coincidencia encontrada generará notificaciones de coincidencia inversa de latente (Reverse latent match), que contienen el UGUID de la latente no resuelta (UL, Unsolved Latent) con la que hubo coincidencia. La transacción de registro o actualización continuará normalmente y se comparará con la base de referencia. Esta búsqueda normal puede dar lugar a una conclusión normal o generar una excepción. El siguiente ejemplo muestra las notificaciones recibidas en una situación en la que hubo una coincidencia con una latente no resuelta seguida de un registro exitoso:

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

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

### Reenvío de una transacción rechazada

Cuando el GBDS reenvía automáticamente una transacción rechazada (`REFUSED`), se envía una notificación para informar del reenvío, con el nuevo tguid asociado:

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

### Eliminación

Al finalizar el proceso de eliminación de una persona o de una biometría en el GBDS, se envía una notificación con el resultado de la operación:

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

El estado `COMPLETED` se envía tanto para la eliminación de una biometría como para la de una persona, al finalizar la ejecución de la tarea.


---

# 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/gbs/es/integracion-del-gbds/flujos-de-notificacion-de-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.
