Integración del GBDS

Introducción

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

El GBDS provee notificaciones asíncronas para operaciones demoradas. Los flujos de notificación están detallados en el Manual de Flujos de Notificación.

La autenticación para todas las llamadas de API se realiza presentando un token válido. Un nuevo token puede ser creado con la llamada createToken. Un token puede y debe ser usado para múltiples llamadas. Crear un nuevo token antes de cada llamada afecta negativamente el rendimiento del sistema.

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

Además, el GBDS sigue un índice para identificación biométrica, según se representa en la tabla a continuación:

Índice

Biometría

Meñique Izquierdo

Anular Izquierdo

Medio Izquierdo

Índice Izquierdo

Pulgar Izquierdo

Pulgar Derecho

Índice Derecho

Medio Derecho

Anular Derecho

Meñique Derecho

Rostro

Iris Izquierda

Iris Derecha

Firma

Interdigital de la Palma Izquierda

Tenar de la Palma Izquierda

Hipotenar de la Palma Izquierda

Interdigital de la Palma Derecha

Tenar de la Palma Derecha

Hipotenar de la Palma Derecha

Palma Izquierda Completa

Writer de la Palma Izquierda

Palma Derecha Completa

Writer de la Palma Derecha

200

Palma Izquierda de Recién Nacidos

210

Palma Derecha de Recién Nacidos

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

Flujo de Registro (Enroll)

En este caso, el usuario quiere insertar una nueva persona en el ABIS. Para ello, el usuario realiza una llamada enroll (una solicitud POST para el endpoint /gbds/v2/people).

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

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

El usuario será notificado cuando el GBDS concluya el procesamiento de la transacción. El usuario también puede consultar el estado de la transacción con la llamada getTransaction (una solicitud GET para el endpoint /gbds/v2/people/transactions/{tguid}).

Si la transacción se completa con éxito (estado ENROLLED), un identificador único de persona (pguid) será generado para operaciones de consulta como getPerson.

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

ENQUEUED

La transacción fue encolada para procesamiento.

PROCESSING

La transacción está siendo procesada.

FAILED

La transacción de registro no pudo ser completada. Esta situación es consecuencia del manejo de una excepción o del control de calidad.

EXCEPTION

El registro generó al menos una excepción, y la transacción permanecerá en este estado hasta que la excepción sea tratada (por la aplicación GBS ETR o programáticamente).

PENDING

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

ENROLLED

El registro se completó con éxito, y la transacción está asociada a un identificador único de persona válido (pguid), que puede ser obtenido con la llamada getTransaction.

REFUSED

La transacción entrante fue rechazada por haber hecho match con otra transacción asociada a una o más excepciones activas pendientes.

Flujo de Actualización (Update)

En este caso, el usuario desea actualizar los datos asociados a una persona ya existente en el ABIS. Si el usuario no tiene el identificador de persona (pguid), debe obtenerlo usando una clave biográfica o un identificador de transacción (tguid):

Para obtener un pguid a partir de claves biográficas, el usuario debe llamar getPGuidUsingKeys (una solicitud GET para el endpoint /gbds/v2/people/pguid).
Para obtener el pguid asociado a un tguid conocido, el usuario debe llamar getTransaction.

Para realizar la actualización, el usuario debe llamar update (una solicitud PUT para el endpoint /gbds/v2/people/{pguid}).

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

Llamadas de actualización que modifiquen datos biométricos serán procesadas de modo similar a transacciones de registro (Enroll), pudiendo generar excepciones y análisis de calidad (estado EXCEPTION y PENDING), y generarán notificaciones para quien inició la transacción. El estado de la transacción también puede ser consultado con llamadas getTransaction.

Llamadas de actualización que modifiquen solo datos biográficos serán procesadas de forma síncrona. La respuesta HTTP contendrá solo un estado OK o ERROR.

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 único pguid o por una clave biográfica.

Para realizar la verificación, el usuario debe llamar search (una solicitud POST para el endpoint /gbds/v2/people/searches). El perfil objetivo de la comparación debe ser dado por una clave biográfica en el parámetro data.keys o por un pguid en data.pguids.

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

MATCH

Los datos biométricos proporcionados hicieron match con el registro de la persona en el ABIS.

NOT_MATCH

Los datos biométricos proporcionados no hicieron match con el registro de la persona en el ABIS.

PERSON_NOT_FOUND

La persona objetivo (pguid o clave biográfica) no fue encontrada en la base de datos.

Un identificador de transacción (data.tguid) también será devuelto, y mayores detalles sobre la operación de verificación pueden obtenerse con la llamada getSearchResult (una solicitud GET para el endpoint /gbds/v2/people/searches/{tguid}).

Verificación con Múltiples GUIDs

El endpoint /gbds/v2/people/searches permite solicitudes de verificación con múltiples PGUIDs o múltiples UGUIDs en el caso de verificación de latentes.

Esto permite algunas nuevas características:

Verificación de varios PGUIDs
- Valida verificación con lista de pguids. Solo si isUlSearch está definido como false.
- Valida verificación con lista de claves, usando el atributo keys.
  - La lista filtra solo una persona.
  - Esta característica es válida solo si isUlSearch está definido como false.
Verificación de varios UGUIDs usando isUlSearch=true.
- Usa el atributo uguids como una lista de strings.
- Valida la verificación con esta lista de uguid. Solo si isUlSearch está definido como true.
Búsqueda de latente en pguids/uguids
- La búsqueda de latente estará activada si isLatentSearch definido como true para búsqueda de pguids. Para búsqueda de uguids el valor es siempre true.

Flujo de Identificación

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

Para realizar la identificación, el usuario debe llamar search (una solicitud POST para el endpoint /gbds/v2/people/searches) dejando vacíos los parámetros data.keys y data.pguids.

En el caso de una búsqueda de identificación, el atributo matcher DEBE debe ser definido como DEFAULT. Usar el valor MOBILE resultará en el retorno de un error al usuario.

Búsquedas de identificación son realizadas de forma asíncrona. Una llamada de búsqueda exitosa devolverá una respuesta HTTP con un identificador de transacción (data.tguid) y un estado (data.status).

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

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

ENQUEUED

La búsqueda está encolada, y aún no ha comenzado a procesarse.

PREPARED, PROCESSING

Estos valores indican que la búsqueda está siendo procesada.

MATCH

La búsqueda fue procesada, y al menos un match fue encontrado. Los matches son devueltos en el campo data.cadidates de la respuesta a getSearchResult.

NOT_MATCH

La búsqueda fue procesada y ningún match fue encontrado.

PERSON_NOT_FOUND

El dominio de búsqueda estaba vacío: los filtros especificados, como lista de pguids y/o filtros de etiquetas resultaron en un conjunto vacío de candidatos.

Flujos de Recuperación de Registro

Esta sección presentará los flujos para recuperar información de perfiles usando el GBDS. Para opciones avanzadas de filtrado en las llamadas de listPeople y listTransactions, consulte el Manual Usando Wildcards para Recuperar Información del GBDS.

Recuperando el Registro de una Única Persona

Para obtener los datos más actuales asociados a una persona específica, el usuario debe llamar getPerson (una solicitud GET para el endpoint /gbds/v2/people/{pguid}).

La respuesta HTTP contendrá los datos biográficos de la persona y la transacción de registro (Enroll) más reciente asociada a ella.

Obteniendo el Pguid a partir de Claves Biográficas

Para obtener el identificador único de una persona (pguid) a partir de una clave biográfica, el usuario debe llamar getPguidUsingKeys (una solicitud GET para el endpoint /gbds/v2/people/pguid).

Obteniendo el Pguid a partir de Datos Biográficos

Para obtener una lista de identificadores de persona (pguids) que hacen match con datos biográficos (y no solo claves), el usuario puede llamar listPeople (una solicitud POST para el endpoint /gbds/v2/people/list).

Es posible realizar una llamada de listPeople proporcionando solamente el valor que será usado para filtrar por clave o biográfico.

Este formato de solicitud solo puede usarse para listas filtradas por claves o biográficos. Si el criterio de filtrado es cualquier otro campo, debe ser especificado en el formato de campo:valor.

Criterios de Campo Restriction

Es posible realizar una llamada de listPeople proporcionando los criterios para filtrar la lista retornada. El campo restriction debe contener un array de objetos que varían de acuerdo con el tipo de dato (representado por el campo type) usado como parámetro de filtrado. Cada llamada puede contener una o más restricciones, los tipos aceptados son: BIOGRAPHIC, DATE, KEY y LABEL. Los objetos para cada tipo están listados abajo:

BIOGRAPHIC:

Campo

Requerido

Tipo

type

Sí. El valor DEBE ser BIOGRAPHIC

String

Sí

String

value

Sí

String

exists

Sí. Por defecto true.

Boolean

matchMode

Por defecto EXACT. Enum: - START - EXACT - ANYWHERE - END - NOT_EQUALS

String

DATE:

Campo

Requerido

Tipo

type

Sí. El valor DEBE ser DATE

String

startTime

Sí. Debe estar en milisegundos.

String

endTime

No. Debe estar en milisegundos

String

KEY:

Campo

Requerido

Tipo

type

Sí. El valor DEBE ser KEY

String

Sí

String

value

Sí

String

exists

Sí. Por defecto true.

Boolean

matchMode

Por defecto EXACT. Enum: - START - EXACT - ANYWHERE - END - NOT_EQUALS

String

LABEL:

Campo

Requerido

Tipo

type

Sí. El valor DEBE ser KEY

String

label

Sí

String

exists

Sí. Por defecto true.

Boolean

Flujo de Transacciones Rechazadas (REFUSED)

El resultado REFUSED ocurrirá en actualizaciones y registros cuando una nueva transacción haga match con una transacción existente que esté asociada a una excepción biométrica pendiente.

Transacciones Síncronas

Cuando una transacción es sometida a una operación síncrona, la respuesta contendrá un campo data.status con el valor REFUSED:

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

Transacciones Asíncronas

En el caso de una transacción de registro sometida asincrónicamente, la respuesta contendrá un campo data.status con el valor ENQUEUED:

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

Recibiendo la Notificación

Cuando el GBDS finaliza el procesamiento de una transacción, el GBS Notifier envía una notificación a un endpoint configurado con el TGUID y el resultado del procesamiento (estado) de la transacción. Si la transacción es rechazada, el Notifier mandará una notificación en el formato:

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

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

Después de recibir la notificación de una transacción rechazada (REFUSED), una llamada de getTransaction debe ser sometida al GBDS con el TGUID como parámetro para que se puedan obtener los detalles que involucran la transacción y sus excepciones.

La operación de getTransaction es descrita en la próxima sección, mientras que la información sobre cómo tratar una transacción rechazada se describe en la sección Tratando una Transacción Rechazada.

Realizando Consulta Activa

Para realizar consulta activa para obtener los resultados de una transacción, una llamada de getTransaction deberá ser sometida al GBDS con el TGUID del registro como un parámetro con el siguiente endpoint:

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 ejemplo abajo:

{
	"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
	}
}

Tratando una Transacción Rechazada (REFUSED)

Como se mencionó previamente, una transacción rechazada ocurre cuando un perfil entrante hace match con uno existente que está vinculado a una excepción activa. Cuando una transacción finaliza con este estado, el perfil entrante es descartado y una nueva transacción debe ser sometida para ese perfil después de que las excepciones activas pendientes sean tratadas.

Después de identificar el registro rechazado y ejecutar las llamadas de getTransaction, el campo failReason de la respuesta de getTransaction contendrá los PGUIDs del perfil de referencia con los que el perfil entrante hizo match. La cantidad de PGUIDs retornada en la respuesta es ilimitada y separada por comas.

Después de que todas las excepciones sean tratadas, el registro rechazado puede ser re-sometido.

El flujo de trabajo completo para resolver registros rechazados es:

El mismo flujo de trabajo puede usarse para resolver actualizaciones rechazadas usando los comandos equivalentes.

Ejemplo:

Registro 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" }
3. Guarde TGUID 1 y PGUID 1

La aplicación ejecuta 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
	}
}

Cree y guarde un mapeo artificial del PGUID 0 al PGUID 1 / TGUID 1

Registro 2 - TGUID 2;

TGUID 2 hace match con PGUID 0;

TGUID 2 - recibe el estado REFUSED porque hizo match con el PGUID 0 que ya estaba vinculado a una 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
	}
}

Guarde el PGUID <PGUID 0> asociado con TGUID 2;
1. Actualice el mapeo indicando que PGUID 0 / PGUID 1 / TGUID 1 / TGUID 2 están vinculados

Un examinador resuelve la excepción generada en el Paso 1:

La aplicación es notificada con:

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

Envíe un nuevo registro para el TGUID 2.

Es posible que un PGUID que hizo match tenga múltiples excepciones vinculadas a él. En ese escenario, todas las excepciones para el PGUID deben ser tratadas antes de intentar re-someter el registro o la actualización rechazada.

Es importante mencionar que el flujo de trabajo arriba debe ser implementado para completar automáticamente las transacciones sin ninguna intervención manual.

En otras palabras, para obtener el resultado final de esta transacción (TGUID 2), es necesario esperar la notificación del GBS Notifier informando el tratamiento de la excepción para la excepción existente (TGUID 1) y ejecutar la llamada de getTransaction para recuperar la información sobre los PGUIDs que hicieron match del GBDS (vea las secciones Recibiendo la Notificación y Realizando Consulta Activa).

Usando Wildcards para Recuperar Información del GBDS

Cuando se recupera información del GBDS usando List Transactions y List People, es posible usar operadores wildcard para filtrar los resultados.

Cuando se realiza una llamada de List Transactions usando el parámetro qualityStatus, los campos key, biographic, y label pueden ser filtrados usando operadores wildcard.

Los operadores wildcard se describen abajo:

List Transactions

Sufijos

Los campos key o biographic pueden contener un id:value o id|value, como por ejemplo Name:John Doe, donde se pueden insertar cuatro sufijos.

[anywhere]: Este es el sufijo por defecto, si ninguno es escrito, este será seleccionado. En este caso, la aplicación buscará por el id o valor proporcionado en cualquier parte de la cadena.
Ejemplo: Si la clave es name[anywhere]:rob, se buscarán nombres (name) como "Robbin" apellidos (surname) "Robarts".
[atstart]: Si este sufijo es usado, la aplicación buscará por el id o valor proporcionado al inicio de la cadena.
Ejemplo: Si la clave es passportNumber:123[atstart], se buscarán números de pasaporte que comiencen con 123 y devolverá todos los casos válidos.
[atend]: Si este sufijo es usado, la aplicación buscará por el id o valor proporcionado al final de la cadena.
Ejemplo: Si la clave es passportNumber:123[atend], se buscarán números de pasaporte que terminen con 123. name[atend]:son buscará nombres (name) y apellidos (surname) que terminen con "son".
[exact]: Si este sufijo es usado, la aplicación buscará por coincidencias idénticas a lo proporcionado en la cadena de búsqueda.
Ejemplo: Si la clave es passportNumber:123[exact], se buscarán números de pasaporte que sean exactamente iguales a 123.

Estos operadores wildcard son SUFIJOS, por lo tanto deben ser insertados DESPUÉS del ID y/o DESPUÉS del VALOR.

Adicionalmente, id y valor pueden tener sufijos distintos para cada uno, por lo que es posible tener operaciones como: name[exact]:rob[atstart], donde se buscarán campos que estén nombrados exactamente name por valores que comiencen con "rob".

Prefijos

El campo de biográficos también puede tener un prefijo. Este prefijo puede usarse solo en el PRIMER biográfico, antes del id. Otros prefijos serán ignorados. Este prefijo definirá qué operación lógica la aplicación ejecutará entre TODOS los campos biográficos y de claves. Los valores aceptados son [and] y [or], siendo el primero el valor por defecto.

Ejemplo: Si el biográfico es [or]id:value, se ejecutará una operación OR en todas las claves y biográficos, como: (Key1 OR Biographic1 OR Biographic2).

Este prefijo puede combinarse con un sufijo, por lo que valores como [or]id:value[exact] son aceptados.

List People

Cuando se realiza una llamada de List People, el parámetro operator puede ser tanto and o or. El operador seleccionado será aplicado en las comparaciones entre key, biographic y label. Luego, una comparación and se hará con el valor de data deseado para el filtrado de los datos.

Ejemplo: Si el operador seleccionado es or, la comparación para filtrar los datos será: ((Key1 OR Biographic1 OR Biographic2 OR Label1) AND Date).

Restrictions matchMode

Dentro del objeto de restricciones (restrictions), es posible seleccionar uno de cinco matchMode cuando la restricción sea un Biográfico o una Clave. Los posibles valores y sus operaciones están listados a continuación.

Todo lo que no sea una letra, un número o un guión bajo es un separador. Un separador entre números o letras causará la tokenización de la palabra/número completo en todos los modos, excepto EXACT y NOT_EQUALS.

En el valor del filtro de restricción, solo el espacio en blanco `` `` es un delimitador y tokenizará las palabras/números. Este comportamiento no ocurre en EXACT y NOT_EQUALS.

El parámetro de búsqueda es sensible a caracteres especiales en letras, como â, é, ñ y otros.

EXACT

La operación exact busca todo el valor proporcionado. El uso de exact no tokenizará la expresión restringida. Este modo diferencia mayúsculas de minúsculas.

Ejemplo: La llamada debe devolver el valor "Jose Arruda". Usar EXACT con "Jose" o "Arruda" funcionará para devolver el valor deseado.

Búsquedas como "Jo" o "rrud" no devolverán Jose Arruda.

Ejemplo 2: La llamada debe devolver un valor numérico de un documento, como "123456". Usando EXACT el valor DEBE ser "123456".

Búsquedas con el valor "123" o "456" no devolverán el valor correcto.

Si el valor se almacena con un separador, el separador deberá estar en el valor de la restricción.

START

La operación de start filtrará los valores tokenizando cada palabra o conjunto de números dividido por un separador.

Ejemplo: Si el usuario está restringiendo START al valor "Jo", algunos resultados posibles pueden ser:
```
Jose Arruda
John Doe
Marie Johnson
```
Ejemplo 2: En caso de que el usuario esté restringiendo START al valor "Jose Arruda", algunos resultados posibles pueden ser:
```
Jose Arruda
Jose Silva
Pedro Thomas Arruda
```
Ejemplo 3: Si el usuario está restringiendo START al valor "123", algunos resultados posibles pueden ser:
```
1234567
123.456
456-123
a-b 123
```
Ejemplo 4: Si el usuario está restringiendo START al valor "123.456", algunos resultados posibles pueden ser:
```
123.456
123.456.789-90
```

ANYWHERE

La operación en anywhere buscará el valor en cualquier parte de la palabra o número.

Ejemplo: Si la restricción del usuario es ANYWHERE para el valor "Jo", algunos resultados posibles pueden ser:
```
Jose Arruda
Major
Pejorative
Banjo
```
Ejemplo 2: Buscar "12" puede devolver:
```
123456
641256
114-4312
a-b 123
```
Ejemplo 3: Si la restricción del usuario es ANYWHERE para el valor "Jo Ru", algunos resultados posibles pueden ser:
```
Jose Arruda
Ruth Silva
Havier Russel
```

END

La operación end buscará el valor al FINAL del token. Como START, esta operación tokenizará las palabras/números por cada separador.

Ejemplo: Si la restricción del usuario END para el valor "son", algunos resultados posibles pueden ser:
```
Eric Johnson
Hudson Santos
```
Ejemplo 2: Si el usuario está restringiendo END al valor "Jose Arruda", algunos resultados posibles pueden ser:
```
Jose Arruda
Jose Silva
Pedro Thomas Arruda
Arruda Bastos
```
Ejemplo 3: Si el usuario está restringiendo END al valor "123", algunos resultados posibles pueden ser:
```
4567123
123.456
456-123
a-b 123
```
Ejemplo 4: Si el usuario está restringiendo END al valor "123.456", algunos resultados posibles pueden ser:
```
123.456
789.123.456
```

NOT_EQUALS

La operación Not equals funciona de modo inverso a la operación EXACT. Filtrará y DESCARTARÁ coincidencias exactas con el valor proporcionado y mostrará TODOS LOS DEMÁS valores. Este modo distingue entre mayúsculas y minúsculas.

Ejemplo: Usar NOT_EQUALS con el valor "Jose" puede devolver:
```
John Doe
Marie Johnson
Josemar Rodrigues
```
Ejemplo 2: Usar NOT_EQUALS con el valor "123" puede devolver:
```
4567123
123456
```

Última actualización hace 4 meses

¿Te fue útil?