1. Introducción¶

Este manual describe brevemente cada flujo estándar de GBDS 4 como una secuencia de llamadas API, que son solicitudes HTTP/HTTPS a un servidor GBDS. Para obtener una referencia completa de las llamadas API de GBDS, consulte la especificación de la API de GBDS.

GBDS 4 proporciona notificaciones asíncronas para operaciones prolongadas. Los flujos de notificación se describen en detalle en el Manual de flujos de notificación.

La autenticación para todas las llamadas API se realiza proporcionando un token válido. Un nuevo token se puede crear con la llamada createToken. Un token se puede y se debe utilizar para varias llamadas. La creación de un nuevo token de autenticación antes de cada llamada afecta negativamente el rendimiento del sistema.

Todos los diagramas de este manual siguen esta convención:

Además, GBDS sigue un índice para la identificación biométrica, como se representa en la siguiente tabla:

Índice	Biometría
0	Meñique izquierdo
1	Anular izquierdo
2	Medio izquierdo
3	Índice izquierdo
4	Pulgar izquierdo
5	Pulgar derecho
6	Índice derecho
7	Medio derecho
8	Anular derecho
9	Meñique derecho
10	Rostro
13	Iris izquierdo
14	Iris derecho
20	Firma
31	Interdigital izquierdo de la palma
32	Thenar izquierdo de la palma
33	Hipotenar izquierdo de la palma
34	Interdigital derecho de la palma
35	Thenar derecho de la palma
36	Hipotenar derecho de la palma
40	Palma izquierda completa
41	Escritor de la palma izquierda
45	Palma derecha completa
46	Escritor de la palma derecha
200	Palma izquierda de recién nacido
210	Palma derecha de recién nacido
900	Control de secuencia - Meñique izquierdo
901	Control de secuencia - Anular izquierdo
902	Control de secuencia - Medio izquierdo
903	Control de secuencia - Índice izquierdo
904	Control de secuencia - Pulgar izquierdo
905	Control de secuencia - Pulgar derecho
906	Control de secuencia - Índice derecho
907	Control de secuencia - Medio derecho
908	Control de secuencia - Anular derecho
909	Control de secuencia - Meñique derecho
940	Control de secuencia - Cuatro dedos izquierdos
941	Control de secuencia - Cuatro dedos derechos
942	Control de secuencia - Dos pulgares

2. Flujo de inscripción¶

En este caso, el usuario desea insertar una nueva persona en el ABIS. Para hacerlo, el usuario realiza una llamada enroll (una solicitud POST al punto final /gbds/v2/people).

Una llamada de inscripción bien formada devolverá una respuesta HTTP con un ID de transacción único (tguid) en data.tguid y una cadena de estado en data.status.

El tguid se utilizará para identificar esta transacción en llamadas futuras y notificaciones asíncronas.

El usuario será notificado cuando la transacción haya sido procesada por GBDS. El usuario también puede consultar el estado de la transacción con la llamada getTransaction (una solicitud GET al punto final /gbds/v2/people/transactions/{tguid}).

Si la transacción se completa con éxito (estado ENROLLED), un ID de persona único (pguid) estará disponible para operaciones de recuperación como getPerson.

El estado de una transacción de inscripción puede ser:

ENQUEUED

La transacción ha sido encolada con éxito para su procesamiento.

PROCESSING

La transacción se está procesando actualmente.

FAILED

La transacción de inscripción no se pudo completar. Esto es consecuencia del tratamiento de excepciones o del tratamiento de análisis de calidad.

EXCEPTION

La inscripción generó al menos una excepción, y la transacción permanecerá en este estado hasta que se trate la excepción (ya sea en la aplicación GBS ETR o programáticamente).

PENDING

La inscripción falló en el análisis automático de calidad, y la transacción permanecerá en este estado hasta que se realice el análisis de calidad (ya sea en la aplicación GBS MIR o programáticamente).

ENROLLED

La inscripción se realizó con éxito, y la transacción está asociada con un ID de persona único válido (pguid) que se puede obtener mediante la llamada getTransaction.

REFUSED

Una transacción de inscripción concluye como REFUSED cuando la transacción entrante tiene coincidencias biométricas con otra transacción que ya está asociada con una excepción biométrica activa.

RESENT_ENROLL

La transacción fue inicialmente rechazada y luego reenviada para la inscripción por ETR.

3. Flujo de actualización¶

En este caso, el usuario desea actualizar los datos asociados con una persona existente en el ABIS. Si el usuario no tiene el ID de persona (pguid), debe recuperarlo utilizando una clave biográfica o un ID de transacción conocido (tguid):

Para obtener un pguid a partir de claves biográficas, el usuario debe realizar una llamada getPGuidUsingKeys (una solicitud GET al punto final /gbds/v2/people/pguid).

Para obtener un pguid asociado con un tguid conocido, el usuario debe realizar una llamada getTransaction.

Para realizar la actualización, el usuario debe utilizar la llamada update (una solicitud PUT al punto final /gbds/v2/people/{pguid}).

Una llamada de actualización bien formada devolverá una respuesta HTTP con un ID de transacción único (tguid) en data.tguid y una cadena de estado en data.status.

Las llamadas de actualización que modifican datos biométricos se procesarán de manera similar a las transacciones de Inscripción, pueden generar excepciones y análisis de calidad (EXCEPTION y PENDING estado) y generarán notificaciones al llamante. El estado de la transacción también se puede consultar con llamadas de getTransaction.

Las llamadas de actualización que modifican solo datos biográficos se procesarán de manera síncrona. La respuesta HTTP contendrá un estado OK o ERROR.

4. Flujo de verificación¶

En este caso, el usuario desea realizar una búsqueda de Verificación (1:1), comparando datos biométricos con una persona específica en el ABIS. El objetivo de la búsqueda debe ser identificado por un pguid o por una clave biográfica.

Para realizar la verificación, el usuario debe utilizar la llamada search (una solicitud POST al punto final /gbds/v2/people/searches). El perfil objetivo para la comparación debe ser determinado ya sea por una clave biográfica en el parámetro data.keys o por un ID de persona en data.pguids.

La respuesta HTTP tendrá el resultado de la verificación en data.status, que puede ser:

MATCH

Los datos de consulta biométricos coincidieron con los datos biométricos de la persona especificada.

NOT_MATCH

Los datos de consulta biométricos no coincidieron con los datos biométricos de la persona especificada.

PERSON_NOT_FOUND

La especificación de persona (pguid o clave biográfica) no se encontró en la base de datos.

También se devolverá un ID de transacción (data.tguid), y se pueden obtener más detalles sobre la operación de verificación con la llamada getSearchResult (una solicitud GET al punto final /gbds/v2/people/searches/{tguid}).

4.1. Verificación con múltiples GUIDs¶

El punto final /gbds/v2/people/searches permite verificar solicitudes con múltiples PGUIDS o búsqueda de verificación UL con múltiples UGUIDS.

Esto permite algunas nuevas características:

Verificar múltiples PGUIDS
- Validar la verificación con una lista de pguid, solo válido si isUlSearch está configurado en false.
- Validar la verificación con una lista de claves, utilizando el atributo keys.
  - La lista filtra solo una persona
  - Esta característica es válida solo si isUlSearch está configurado en false.
Verificar múltiples uguids usando isUlSearch=true.
- Utiliza el atributo uguids como una lista de cadenas.
- Validar la verificación con esta lista de uguid. Válido solo si isUlSearch está configurado en true.
Búsqueda latente en pguids/uguids
- La búsqueda latente se activa con isLatentSearch configurado en true para la búsqueda de pguids. Para la búsqueda de uguids, la búsqueda latente siempre es true.

5. Flujo de identificación¶

En este caso, el usuario desea realizar una búsqueda de Identificación (1:N), comparando datos biométricos con muchos (posiblemente todos) los registros en el ABIS.

Para realizar la identificación, el usuario debe utilizar la llamada search (una solicitud POST al punto final /gbds/v2/people/searches) con los parámetros data.keys y data.pguids vacíos.

Warning

En el caso de una búsqueda de identificación, el valor del atributo matcher DEBE ser DEFAULT. Usar MOBILE como valor del atributo devolverá un error en los flujos de identificación.

Las búsquedas de identificación se realizan de forma asíncrona. Una llamada exitosa a la búsqueda devolverá una respuesta HTTP con un ID de transacción (data.tguid) y un estado (data.status).

El usuario recibirá una notificación cuando se complete la búsqueda. El usuario también puede consultar el estado de la transacción con la llamada getSearchResult (una solicitud GET al punto final /gbds/v2/people/searches/{tguid}).

El estado de la transacción de búsqueda puede ser:

ENQUEUED

La búsqueda está en cola y aún no ha comenzado a procesarse.

PREPARED, PROCESSING

Estos valores de estado indican que la búsqueda se está procesando.

MATCH

La búsqueda ha sido procesada y se encontró al menos una coincidencia. Las coincidencias se devuelven en el campo data.candidates de la respuesta a getSearchResult.

NOT_MATCH

La búsqueda ha sido procesada y no se encontraron coincidencias.

PERSON_NOT_FOUND

El dominio de búsqueda estaba vacío: los filtros especificados, como la lista de pguids y/o los filtros de etiquetas, dieron como resultado un dominio de búsqueda vacío.

6. Flujos de recuperación de perfiles¶

Esta sección presentará los flujos para recuperar información de perfil utilizando GBDS. Para opciones de filtrado avanzado en las llamadas listPeople y listTransactions, consulte el Manual de Usando comodines para recuperar datos de GBDS.

6.1. Recuperación de perfil de una sola persona¶

Para obtener la información más actualizada asociada con una persona específica, el usuario debe realizar la llamada getPerson (una solicitud GET al punto final /gbds/v2/people/{pguid}).

La respuesta HTTP contendrá los datos biográficos de la persona y la transacción de inscripción más reciente asociada con ella.

6.2. Recuperación de pguid a partir de claves biográficas¶

Para obtener el ID de una persona (pguid) a partir de una clave biográfica, el usuario debe realizar la llamada getPguidUsingKeys (una solicitud GET al punto final /gbds/v2/people/pguid).

6.3. Recuperación de pguid a partir de datos biográficos¶

Para obtener una lista de IDs de personas (pguids) que coincidan con los datos biográficos (no solo claves únicas), el usuario puede realizar la llamada listPeople (una solicitud POST al punto final /gbds/v2/people/list).

Note

Es posible realizar una llamada a listPeople proporcionando solo el “valor” que se utilizará para filtrar por clave o biográfico.

Warning

Este formato de solicitud solo se puede utilizar para listas filtradas por claves o datos biográficos. Si los criterios de filtro son cualquier otro campo, deben especificarse en un formato “campo:valor”.

6.3.1. Criterios de restricción¶

Es posible realizar una llamada a listPeople proporcionando criterios para filtrar la lista devuelta. El campo restriction debe contener una matriz de objetos que varían según el tipo de datos utilizado como parámetro de filtro. Cada llamada puede contener una o más restricciones, y los tipos aceptados son BIOGRÁFICO, FECHA, CLAVE y ETIQUETA. Los objetos para cada tipo se enumeran a continuación:

BIOGRAPHIC:

Fields	Required	Type
type	Yes. Value must be BIOGRPAHIC	String
id	Yes	String
value	Yes	String
exists	Yes. Default true.	Boolean
matchMode	Default EXACT. Enum: - START - EXACT - ANYWHERE - END - NOT_EQUALS	String

DATE:

Fields	Required	Type
type	Yes. Value must be DATE	String
startTime	Yes. Must be in milliseconds.	String
endTime	No. Must be in milliseconds.	String

KEY:

Fields	Required	Type
type	Yes. Value must be KEY	String
id	Yes	String
value	Yes	String
exists	Yes. Default true.	Boolean
matchMode	Default EXACT. Enum: - START - EXACT - ANYWHERE - END - NOT_EQUALS	String

LABEL:

Fields	Required	Type
type	Yes. Value must be KEY	String
label	Yes	String
exists	Yes. Default true.	Boolean

7. Flujo de transacciones rechazadas¶

El resultado REFUSED o rechazado se producirá en actualizaciones e inscripciones cuando la nueva transacción coincida con una transacción existente que esté asociada con una excepción biométrica pendiente.

7.1. Transacciones síncronas¶

Cada vez que se envía una transacción como operación síncrona, la respuesta contendrá un campo data.status con el valor REFUSED:

{
  "data":
  {
         "status":"REFUSED", "tguid": "string"
  }
}

7.2. Transacciones asincrónicas¶

En el caso de las transacciones de inscripción enviadas como operaciones asincrónicas, sus respuestas contendrán un campo data.status con el valor ENQUEUED:

{
  "data":
  {
         "status":"ENQUEUED", "tguid": "string"
  }
}

7.2.1. Recepción de una notificación¶

Cada vez que GBDS termina de procesar una transacción, GBS Notifier envía una notificación a un punto final configurado con su TGUID y resultado de procesamiento (estado). Si se rechaza una transacción, el notificador enviará una notificación de la siguiente manera:

{
   "operation": "ENROLL", "tguid": "string", "status": "REFUSED"
}

o

{
   "operation": "UPDATE", "tguid": "string", "status": "REFUSED"
}

Important

Después de recibir una notificación para una transacción REFUSED, se debe enviar una llamada getTransaction a GBDS con su TGUID como parámetro para obtener los detalles de las transacciones y excepciones involucradas.

La operación getTransaction se describe en la siguiente sección, mientras que la información sobre cómo manejar una transacción REFUSED se muestra en la sección Manejo de una transacción REFUSED.

7.2.2. Realización de una encuesta activa¶

Para realizar la encuesta activa de un resultado de transacción, se debe enviar una llamada get transaction a GBDS con el TGUID de inscripción como parámetro al siguiente punto final:

http://<ip>:8085/gbds/v2/people/transactions/{tguid}

El resultado de esta llamada contendrá un campo data.status con el valor REFUSED, como se muestra en el siguiente ejemplo:

{
   "data":
   {
         "tguid": "string", "pguid": "string", "status": "REFUSED", "timestamp": 0, "progress": 0, "Candidates": [], "Person": {}, "qualityAnalysis": {}, "failReason": "Enroll matches 2 person(s) that are already involved in a pending exception. PGUIDs: 75ABF575-6825-41D7-A2A7-2C0D64CF9FE7, B393C481-C0AF-456C-9155-1510AFDC7D86", "isCurrentTransaction": false
   }
 }

7.3. Manejo de una transacción REFUSED¶

Como se mencionó anteriormente, una transacción REFUSED ocurre cuando el perfil del entrante coincide con uno existente que está vinculado a una excepción activa. Cuando una transacción finaliza con este estado, el perfil del entrante se descarta y se debe enviar una nueva transacción para este perfil después de que se haya tratado la excepción activa pendiente.

Después de identificar la inscripción REFUSED y realizar las llamadas getTransactions, el campo “failReason” de la respuesta getTransaction contendrá los PGUID de los perfiles de referencia con los que coincidió el perfil del entrante. La cantidad de PGUID devueltos no está limitada y se separan por comas.

Después de que todas las excepciones hayan sido tratadas, la inscripción REFUSED puede ser reenviada. Este es el flujo de trabajo completo para tratar las inscripciones REFUSED:

Important

El mismo flujo de trabajo se puede utilizar para tratar actualizaciones rechazadas, utilizando los comandos equivalentes.

Ejemplo:

Inscripción 1 - Genera TGUID 1 y PGUID 1;
1. TGUID 1 - crea una excepción biométrica con un PGUID 0 ya existente;
2. La aplicación es notificada con:
```
{
    "operation": "ENROLL", "tguid": "<TGUID 1>", "status": "EXCEPTION"
}
```
1. Guardar TGUID 1 y PGUID 1

La aplicación realiza GET /gbds/v2/exceptions/{tguid}

Y la respuesta es:

{
   "data": [
   {
      "transactionTimestamp": 0, "match": {
         "matchedPersonPguid": "PGUID 0", "matchedPersonTguid": "TGUID 0", "biometricMatches": []
      }
   }
   ], "pagination": {
   "total": 0, "count": 0, "pageSize": 0, "currentPage": 0, "totalPages": 0
   }
}

Crear y guardar un mapeo artificial de PGUID 0 a PGUID 1 / TGUID 1

Inscripción 2 - TGUID 2;

TGUID 2 coincide con PGUID 0;
TGUID 2 - recibe el estado REFUSED porque coincide con PGUID 0 ya en excepción;

{
    "data":
    {
        "tguid": "string", "pguid": "string", "status": "REFUSED", "timestamp": 0, "progress": 0, "Candidates": [], "Person": {}, "qualityAnalysis": {}, "failReason": "Enroll matches 1 person(s) that are already involved in a pending exception. PGUIDs: PGUID 0", "isCurrentTransaction": false
    }
}

Guardar el PGUID coincidente <PGUID 0> asociado con TGUID 2;
1. Actualizar el mapeo para indicar que PGUID 0 / PGUID 1 / TGUID 1 / TGUID 2 están todos vinculados

Un examinador resuelve la excepción generada en el Paso 1: a. La aplicación es notificada con:

{
    "operation": "TREAT_EXCEPTION", "tguid": "<TGUID 1>", "status": "OK", "treatment": "TREATMENT_OPTION"
}

Enviar una nueva inscripción para TGUID 2.
1. Esto generará un TGUID 3. Guarde TGUID 2 y 3 para el siguiente paso.

Warning

Es posible que un PGUID coincidente tenga varias excepciones vinculadas a él. En este escenario, todas las excepciones para el PGUID dado deben ser tratadas antes de intentar reenviar la inscripción o actualización rechazada.