Biometría - APIs WEB para los procesos de identificación
A continuación, se describen las principales funciones del servicio biométrico de TOC Perú para la administración de los procesos de identificación por parte del cliente.
El funcionamiento de los procesos de identificación está pensado para ser usados de manera simple y flexible, y, a su vez, entregando la confianza del resultado de estos soportados por tecnologías biométricas certificadas. La creación y resolución de un proceso de identificación se puede resumir en 3 pasos:
graph TD;
A[Autenticación] --> B[Creación de proceso de ID];
B --> C[Resolución de biometría];Los 2 primeros pasos son gestionados mediante las APIs WEB del sistema de biometría de TOC Perú, por lo que la presente documentación explica el uso de los recursos necesarios para dichas etapas. El tercer paso del flujo anteriormente mostrado consiste en la resolución del proceso biométrico, el cual es gestionado por el cliente web o los SDKs de la integración de la biometría a los procesos del cliente.
Ambientes
El sistema de biometría cuenta con 3 ambientes de trabajo: desarrollo, calidad y producción. Esto se traduce en que cada ambiente tiene una URL base distinto (base URL):
- Desarrollo:
https://apifacialdev.identia.pe - Calidad:
https://apifacialqa.identia.pe - Producción:
https://apifacialprod.identia.pe
Estos 3 ambientes se encuentran aislados entre sí, por lo que los datos de una cuenta creada en un ambiente no estarán presentes en los otros (por ende, se requieren credenciales distintas para cada ambiente).
Autenticación
Para poder acceder a las APIs del backend y a sus recursos, el cliente deberá primero obtener un token de acceso, el cual debe ser presentado a al backend dentro del parámetro Authorization en los headers de las llamadas a las APIs.
Para obtener el token de acceso, el cliente debe llamar al endpoint /api/auth/login con un método POST, dentro del cual debe incluir las credenciales que se deben autorizar. El token de acceso tiene un tiempo de vida de 15 minutos.
Método POST
En el body del request POST, el cliente debe presentar las credenciales de acceso. Cada credencial de acceso que el cliente posea podría tener scopes distintos, por lo que pueden ser usadas para casos de uso específicos, limitando el acceso a los recursos que no sean necesarios para dichos casos y así mejorar la seguridad y trazabilidad.
Los parámetros a incluir dentro del body son los siguientes:
username: El nombre de la entidad dueña de los recursos administrados por el backend (posee parámetros, procesos de identificación, usuarios). Formato: Dominio de la entidadclientname: Identificador de la credencial que se utilizará para acceder a los recursos del usuario establecidos al momento de crear la credencial. Formato: Correo electrónicopassword: Es el secret establecido para la credencial que se utilizará
Si las credenciales son correctas, el backend emitirá un token de acceso para que pueda ser usado por el cliente y así acceder a sus recursos.
Ejemplo de solicitud:
Tipo de request:\
POSTrawBody:
Ejemplo de respuesta (código 200):
Tipo de contenido:\
application/jsonBody:
Nota
El encabezado de autorización debe incluir el token en el siguiente formato: jwt-bearer aa.bb.cc
Ejemplo de respuesta (código 404):
Tipo de contenido:\
raw/textBody:\
not found
Proceso de identificación
Los procesos de identificación son gestionados desde el endpoint /api/id_process. Este endpoint le permitirá al cliente crear procesos de identificación, así como también consultarlos y obtener un detalle de estos.
Método PUT
El cliente podrá crear un proceso de identificación llamando al endpoint /api/id_process con el método PUT. Este método sólo puede ser utilizado presentando un token de acceso que incluya el scope id_process:put.
En el body del request, el cliente deberá pasar todos los parámetros que permitan configurar de la manera deseada el proceso de identificación. A continuación, se describen los parámetros configurables:
challenges: Array (JSON string) que indica las validaciones que deben superar los datos de la persona a identificar. En el Anexo 1 se definen los distintos tipos de validaciones.built_challenge_keyword: Al igual que el parámetro challenges, este parámetro permite definir las validaciones que se hacen sobre los datos de la persona a identificar. Sin embargo, el arreglo de validaciones es determinado de acuerdo con un lookup basado en palabras claves previamente definido por el integrador (mapeo de strings a arrays de challenges). Para hacer uso de esta función, debe configurar modalidades y procesos en el backoffice de su cuenta.(Parámetro opcional)description: Información relativa al proceso de identificación reconocible por el cliente. Le permitirá al cliente hacer búsquedas parciales o totales sobre el valor de este parámetro.(Parámetro opcional)expires: Este parámetro define el tiempo de expiración (en segundos) después del cual el proceso de validación expira. Una vez alcanzado este límite, la persona a identificar no podrá completar la validación, y el proceso finalizará con un resultado negativo por expiración. Si no se especifica un valor para este parámetro, se aplicará el valor por defecto de 900 segundos (15 minutos). (Parámetro opcional)doc_id: Número o texto identificador de la persona que deberá superar el proceso de identificación (ej.: DNI). Este valor debe coincidir con el ID que se logre obtener desde el documento de identidad, RENIEC u otras fuentes de datos con las que se haga una comparación.-
nat: Código que le indica al sistema el tipo de número de identificación (país emisor y/o contexto) para las validaciones durante el proceso de identificación.Tipos de NAT Formato de ID Descripción PER12345678Número de identidad nacional Peruano (DNI) CHL12345678-9Número de identidad nacional Chileno (RUN) PERPASS1234567891Número de pasaporte peruano PERCE123456789123Número del carnet de extranjeria peruano Nota
Los códigos de país utilizados en el sistema se basan en el estándar internacional ISO 3166, que proporciona códigos únicos para identificar países y territorios a nivel mundial. Lista de códigos
-
urlCallback: URL de un servicio del integrador (endpoint, webhook, URL firmada, etc) a la que el backend de TOC Perú realizará un request POST una vez haya concluido el proceso de identificación. La data biométrica es adjuntada en el cuerpo del request(revisar urlCallback).(Parámetro opcional)
Ejemplo de datos enviados en el POST:
{
"id": "aaa.123.bbb",
"msg": "success",
"result": true,
"description": "Aplicativo:1 Canal:2",
"images": {
"selfie": "base64",
"doc": { "front": "base64", "back": "base64" }
},
"confidence": 1.0,
"details": {
"liveness": {
"selfie": {
"confidence": 1.0,
"result": true
}
}
}
}
Nota
La sección details dentro del POST es variable según los challenges seteados en el proceso biométrico
Nota
Es posible agregar una cabecera HTTP personalizada a la solicitud POST. Esta cabeceras debe cumplir con lo siguiente:
- Comenzar con el prefijo "X-"
- Contener valores alfanuméricos
- Pueden incluir los símbolos guion (-), guion bajo (_) y punto (.)
-
urlRedirect: Para las integraciones WEB, el cliente podrá establecer una URL de redirección a la cual será redirigida la persona a identificar luego de finalizar el proceso de identificación. (Parámetro opcional) -
personal_info: El integrador podrá proveer la información personal de la persona a identificar si el proceso de validación que se esté creando requiere de una comparación de datos personales contra una fuente. De lo contrario, esta información será consultada a la persona a identificar. La data de este parámetro es un string JSON que puede contener tanto el nombre de la persona (given_name) como el apellido (family_name). (Parámetro opcional)
Ejemplo en el que integrador incluye ambos datos:
-
urlWebSdkUiOrigin: URL del dominio de origen que se encuentre integrando el SDK web (ej.: https://your.domain). Este parámetro es opcional y sólo debe usarse cuando se trate de integraciones con el SDK web. (Parámetro opcional) -
max_tries: El parámetro permite al integrador especificar el número máximo de intentos permitidos para completar uno o varios desafíos dentro de un proceso biométrico. Si no se proporciona un valor, el sistema asumirá un intento único por defecto. Este parámetro controla la cantidad de oportunidades internas para superar los desafíos antes de considerar el proceso como fallido. (Valor recomendable 3) revisar Número de intento
Ejemplo de solicitud:
Tipo de request:\
PUTx-www-form-urlencodedHeaders:
Authorization: jwt-bearer aaa.bbb.cccBody:
Como resultado del método PUT, el cliente recibirá el ID del nuevo proceso de identificación creado. Este ID es único para cada proceso de identificación, y sólo podrá ser resuelto (por la persona a quién se pretende identificar) previo al tiempo de expiración y mientras se encuentre en estado pending.
Ejemplo de respuesta (código 200):
Tipo de contenido:\
application/jsonBody:
Consumo de proceso de validación
Este ID debe ser usado en las integraciones móviles (SDKs Android/iOS) así como también en la integración WEB para iniciar el proceso de identificación. En esta última, la persona a identificar deberá ser redirigida a {baseURL}/ui/id_process/{ID}. Ejemplo de URL para el usuario final: https://apifacialdev.identia.pe/ui/id_process/aa.12.bb
Personalización gráfica
Si has creado una personalización de la interfaz en el Backoffice, puedes agregarlo a la URL final, simplemente agrega el PERSONALIZATION_ID como valor de del parametro styles_id de la siguiente manera {baseURL}/ui/id_process/{ID}?styles_id={PERSONALIZATION_ID}&v=2a, Ejemplo de URL para el usuario final: https://apifacialdev.identia.pe/ui/id_process/aa.12.bb?styles_id=cccccc....cccccc&v=2a
Error por bloqueo de número de identidad
Un error 423 podrá ser entregado al crear un proceso de validación si el número de identidad indicado en los parámetros (doc_id) ha sido bloqueado por exceder el número máximo de validaciones fallidas según lo configurado en los parámetros de las reglas de negocio de la blacklist en el backoffice.
En el cuerpo de la respuesta se encuentran presentes las siguientes propiedades:
msg: indica la regla de negocio de la blacklist que ha gatillado el bloqueo del número de identidad. Esta puede tomar el valor demanualsi el bloqueo se realizó manualmente. De lo contrario,msgcomenzará conparams:blacklist_id:y continuará con el nombre de la regla de bloqueo.until: fecha de expiración del bloqueo de la identidad en formatoAAAAMMDDThh:mm:ss+00:00.
Ejemplo de respuesta (código 423):
Tipo de contenido:\
application/jsonBody:
Método GET
El cliente podrá acceder a la información de uno o varios procesos de identificación mediante una llamada al endpoint /api/id_process con el método GET. Sólo puede ser consumido con un token de acceso que incluya el scope id_process:read. Mediante los parámetros incluidos en el body de la solicitud, el cliente podrá filtrar los procesos de identificación que sean retornados con esta llamada.
Los parámetros a incluir dentro de la búsqueda son opcionales y pueden ser los siguientes:
creation_start: el backend retornará solo aquellos procesos de identificación cuya fecha de creación sea mayor o igual a la establecida en este parámetro. La fecha debe ir en formatoAAAAMMDDThh:mm:ss+00:00. Los últimos 6 caracteres del formato de la fecha corresponden a la zona horaria (GMT), por lo que deben ser reemplazados por la correspondiente al contexto del cliente.creation_end: el backend retornará solo aquellos procesos de identificación cuya fecha de creación sea menor a la establecida en este parámetro. La fecha debe ir en formatoAAAAMMDDThh:mm:ss+00:00. Los últimos 6 caracteres del formato de la fecha corresponden a la zona horaria (GMT), por lo que deben ser reemplazados por la correspondiente al contexto del cliente.status: el cliente podrá filtrar los procesos de identificación según el estado en el que estos se encuentren. Este parámetro sólo puede tomar los valores"pending"o"finished".result: el cliente podrá filtrar los procesos de identificación según el resultado de este. Este parámetro sólo puede tomar los valorestrueofalse.description: El cliente podrá filtrar según el texto presente en la propiedad description de los procesos de identificación. Se deben declarar dentro de un arreglo (string de tipo JSON) los valores a buscar los valores que el sistema debe buscar dentro del description de los procesos de identificación.per_id: si el proceso de identificación incluye el ID de la persona (ej.: DNI), el cliente podrá obtener estos procesos filtrando por el ID nacional de una determinada persona.process_id: permite buscar un proceso de identificación en específico mediante su coincidencia exacta con el ID establecido en este parámetro. Si este parámetro es usado, todos los demás parámetros de búsqueda son ignorados.limit: Número máximo de procesos de identificación a reportar.order: los procesos de identificación son ordenados según la fecha de creación. Este parámetro booleano permite que la búsqueda ocurra de mayor a menor fecha de creación (false) o viceversa (true).last_item: este parámetro corresponde a la representación json (string) del proceso de identificación desde el cual se quiere realizar la búsqueda. Este parámetro es útil cuando la búsqueda realizada retorna más procesos de los permitidos por el límite, por lo que, si dentro de los elementos retornados no se encuentra el deseado, un nuevo llamado para realizar la búsqueda conservando los parámetros, pero incluyendo este, permitirá hacer que la búsqueda sea realizada desde el last_item en adelante.tz: Este parámetro indica el formato de zona horaria que se utilizará para las fechas en el campodate. Por ejemplo, para la hora peruana se debe especificar-05:00. Si no se proporciona un valor para este parámetro, se utilizará el valor por defecto de0:00.
En base a los parámetros, el backend retornará una colección de procesos de identificación coincidentes con la búsqueda (completa o incompleta).
Ejemplo de solicitud:
Tipo de request:\
GETParámetros de la query (URL):
Ejemplo de respuesta (código 200):
Tipo de contenido:\
application/jsonBody:
{ "id_process": [ { "access_counter": 1, "challenges": [ ["liveness:selfie", "match:ocr:id", "match:portrait:selfie"] ], "challenges_retries": { "liveness:selfie": 0, "match:ocr:id": 0, "match:portrait:selfie": 0 }, "client_id": "2cf5Jc....N6Ghkyp", "confidence": 0.7178097, "date": "2024-11-28T18:25:04-05:00", "description": "Aplicativo:PCDI Canal:test", "details": { "liveness": { "selfie": { "confidence": 0.7178097, "result": true } }, "match": { "ocr": { "id": { "confidence": 1, "result": true } }, "portrait": { "selfie": { "confidence": 0.9734558868408203, "result": true } } } }, "doc_id": "11111111", "doc_type": "", "exp": "2024-11-28T18:40:04-05:00", "fec_result": "2024-11-28T18:25:51-05:00", "id": "dddddd.eeeeeee.ffffff", "max_tries": 3, "msg": "success", "nat": "PERCE", "resolve_ip": "0.0.0.0", "result": true, "status": "finished", "user_agent": "Mozilla/5.0" }, { "access_counter": 1, "challenges": [["liveness:selfie"]], "challenges_retries": { "liveness:selfie": 0 }, "confidence": 0.7977935, "date": "2024-11-28T12:47:26-05:00", "description": "Aplicativo:PCDI Canal:test", "details": { "liveness": { "selfie": { "confidence": 0.7977935, "result": true } } }, "doc_id": "11111111", "doc_type": "", "exp": "2024-11-28T13:02:26-05:00", "fec_result": "2024-11-28T12:47:46-05:00", "id": "aaaaaa.bbbbbbb.ccccc", "max_tries": 3, "msg": "success", "nat": "PER", "resolve_ip": "0.0.0.0", "result": true, "status": "finished", "urlCallback": "", "urlWebSdkUiOrigin": "", "user_agent": "Mozilla/5.0" } ], "last_item": { "date": 1732835467, "id": "2331rtgwbe", "usr_id": "ecd...878" } }
Nota
-
Si en una búsqueda inicial no se identifican procesos coincidentes con los atributos enviados, el sistema retornará un parámetro
last_itemen la respuesta. Este valor debe incluirse en el siguiente request utilizando el formatoencodeURIComponent. -
El procedimiento debe repetirse en cada iteración, enviando el nuevo valor de
last_itemretornado, hasta que el sistema devuelva un valornull, lo que indicará que no hay más elementos por procesar. -
El API GET no incluye las imágenes en la respuesta. Esto es debido a que no almacenamos imágenes resultantes en nuestra base de datos.
Ejemplo de respuesta (código 200):
Tipo de contenido:\
application/jsonBody:
{ "id_process": [ { "access_counter": 1, "challenges": [["liveness:selfie"]], "challenges_retries": { "liveness:selfie": 0 }, "confidence": 0.7977935, "date": "2024-11-28T12:47:26-05:00", "description": "Aplicativo:PCDI Canal:test", "details": { "liveness": { "selfie": { "confidence": 0.7977935, "result": true } } }, "doc_id": "11111111", "doc_type": null, "exp": "2024-11-28T13:02:26-05:00", "fec_result": "2024-11-28T12:47:46-05:00", "id": "aaaaaa.bbbbbbb.ccccc", "max_tries": 3, "msg": "success", "nat": "PER", "resolve_ip": "0.0.0.0", "result": true, "status": "finished", "urlCallback": "", "urlWebSdkUiOrigin": "", "user_agent": "Mozilla/5.0" } ], "last_item": null }
Propiedades de un proceso de identificación
En la descripción anterior, se pueden observar las propiedades asociadas a cada proceso de identificación. A continuación, se detalla el significado de cada una:
access_counter: Número de intentos de iniciar el proceso de identificación del lado del usuario finalchallenges: Arreglo que enlista las validaciones realizadas en el proceso de validaciónchallenges_retries: Diccionario donde se contabiliza el número de intentos por challegenconfidence: El valor mínimo de los confidence de los challengesdate: Fecha de creación del proceso de identificación en formatoAAAAMMDDThh:mm:ss+00:00.description: Texto asociados por el cliente al proceso de identificación.detail: Es un conjunto de datos que detalla sobre el resultado de las distintas validaciones realizadas durante el proceso de identificación. Este detalle incluye tanto el resultado como el grado de confianza (escala continua del 0 al 1) por cada tipo validación hecho en el proceso de identificación.doc_id: Identificador nacional (ej.: DNI) de la persona cuyo documento o ficha RENIEC debió coincidir en los procesos de comparación de datosdoc_type: Tipo de documento usado por la persona a identificar para pasar por el proceso de identificación.exp: Fecha de expiración del proceso biométrico en formatoAAAAMMDDThh:mm:ss+00:00.fec_result: Fecha en la que se resolvió el proceso biométrico en formatoAAAAMMDDThh:mm:ss+00:00.id: Identificador único del proceso de identificaciónmax_tries: Número de intentos seteado al momento de crear el proceso biométricomsg: Texto que entrega el motivo del resultado del proceso de validación en caso de que este sea negativo. Ver sección Mensajes de errornat: Código que le indica al sistema el tipo de número de identificación (país emisor y/o contexto) para las validaciones durante el proceso de identificación.resolve_ip: IP desde la cual se resolvió el proceso de identificación (posiblemente más de una IP si hubo un proxy de por medio)result: Resultado del proceso de identificación. Cuando toma el valortrue, quiere decir que el proceso de identificación finalizó con éxito, mientras que un valorfalsesignifica que la persona no pudo ser identificada correctamente. Si el valor esnull, esto indica que el proceso de identificación ha expirado.status: Estado del proceso de identificación. Puede tomar los valores"pending"o"finished".urlCallback: la urlCallback que se seteó al crear el proceso biométricouser-agent: Información del dispositivo en el cual se resolvió el proceso de identificación
Registros faciales
El integrador podrá indexar rostros a su registro facial para posteriormente utilizar dicho registro en una validación biométrica.
Un rostro es indexado luego de un proceso de verificación biométrica exitoso, siempre y cuando el integrador haya establecido que dicho proceso de validación debe incluir dicho proceso. En otras palabras, el proceso de validación debe incluir el challenge register:face (ver Anexo 1).
La API /api/face_db de los registros faciales le permitirán al integrador realizar búsquedas en sus registros faciales, ver los detalles de cada registro (fecha de creación, token facial, entre otros), y también eliminar un registro facial.
Método GET
Este método le permite al integrador acceder a sus registros faciales para revisar los detalles de cada uno de estos. Una vez finalizado el proceso de verificación biométrica que instruye el indexado del rostro, este index es asociado al número de identificación del usuario final (ej.: DNI). En otras palabras, los registros faciales son una relación 1 a 1 entre los números de identificación y los usuarios finales.
Los parámetros opcionales que se pueden incluir en la búsqueda son los siguientes:
creation_start: el backend retornará solo aquellos registros faciales cuya fecha de creación sea mayor o igual a la establecida en este parámetro. La fecha debe ir en formatoAAAAMMDDThh:mm:ss+00:00. Los últimos 6 caracteres del formato de la fecha corresponden a la zona horaria (GMT), por lo que deben ser reemplazados por la correspondiente al contexto del cliente.creation_end: el backend retornará solo aquellos registros faciales cuya fecha de creación sea menor a la establecida en este parámetro. La fecha debe ir en formatoAAAAMMDDThh:mm:ss+00:00. Los últimos 6 caracteres del formato de la fecha corresponden a la zona horaria (GMT), por lo que deben ser reemplazados por la correspondiente al contexto del cliente.limit: Número máximo de registros faciales a reportar.order: los registros faciales son ordenados según la fecha de creación. Este parámetro booleano permite que la búsqueda ocurra de mayor a menor fecha de creación (false) o viceversa (true). Es ignorado si se utiliza el parámetroper_id.last_item: este parámetro corresponde a la representación json (string) del registro facial desde el cual se quiere realizar la búsqueda. Este parámetro es útil cuando la búsqueda realizada retorna más registros de los permitidos por el límite, por lo que, si dentro de los elementos retornados no se encuentra el deseado, un nuevo llamado para realizar la búsqueda conservando los parámetros, pero incluyendo este, permitirá hacer que la búsqueda sea realizada desde el last_item en adelante.per_id: la búsqueda se podrá filtrar recogiendo sólo aquellos registros faciales asociados a DNIs que comiencen con el texto descrito con este parámetro. Sólo puede ser utilizado si se estableció el parámetro nat.nat: Nacionalidad/contexto de identificación del número de identidad asociado al registro facial (para un DNI de Perú, este valor debe serPER)
En base a los parámetros, el backend retornará una colección de registros faciales coincidentes con la búsqueda (completa o incompleta).
Ejemplo de solicitud:
Tipo de request:\
GETParámetros de la query (URL):
Ejemplo de respuesta (código 200):
Tipo de contenido:\
application/jsonBody:
Propiedades de un registro facial
En la descripción anterior, se pueden observar las propiedades asociadas a cada registro facial. A continuación, se detalla el significado de cada una:
date: Fecha de creación del registro facial en formatoAAAAMMDDThh:mm:ss+00:00.process_id: ID del proceso de validación biométrico que instruyó el indexado del rostro.per_id: Número de identidad (DNI) del usuario final cuyo rostro fue indexado al registro facial del integrador.nat: nacionalidad/sistema de identificación correspondiente al número de identidad del usuario final cuyo rostro fue indexado al registro facial del integrador.face_id: Token que representa el mapa facial del rostro indexado en el registro facial del integrador.
Método DELETE
Este método le permitirá al integrador eliminar un determinado rostro de su registro facial.
Los parámetros que se deben incluir en el body del request son los siguientes:
nat: Nacionalidad/sistema de identificación al que pertenece el número de identificación del usuario final cuyo registro facial será eliminado.per_id: Número de identificación del usuario final cuyo registro facial será eliminado.
El sistema buscará y eliminará el registro facial perteneciente al ID usuario final determinado por el integrador, entregando un bool del resultado final de dicha operación (una respuesta positiva significa que la eliminación fue exitosa).
Ejemplo de solicitud:
Tipo de request:\
DELETEx-www-form-urlencodedHeaders:
Authorization: jwt-bearer aaa.bbb.cccBody:
Ejemplo de respuesta (código 200):
Tipo de contenido:\
raw/textBody:\
ok
Registros de actividad
La API /api/logs permite al integrador poder consultar los registros de actividad de la cuenta. Estos registros se agrupan en distintas categorías, y se pueden filtrar por fecha, por resultado de actividad, entre otros.
Método GET
Este método le permitirá al integrador parametrizar la consulta de los registros de actividad. Como parámetro obligatorio, el integrador debe definir el tipo de registro de actividad que se quiere consultar mediante el parámetro group.
Los parámetros que se deben incluir en la query (URL) del request son los siguientes:
Parámetros generales
group(requerido): Define el tipo de registros que se retornan. Este parámetro puede tomar los valores"access_logs","reniec","img_logs","urlcallback"o"telemetry". Ver más detalles en la sección Tipos de grupos de logs.creation_start: El backend retornará solo aquellos registros de actividad cuya fecha de creación sea mayor o igual a la establecida en este parámetro. La fecha debe ir en formatoAAAAMMDDThh:mm:ss+00:00. Los últimos 6 caracteres del formato de la fecha corresponden a la zona horaria (GMT), por lo que deben ser reemplazados por la correspondiente al contexto del cliente.creation_end: El backend retornará solo aquellos registros de actividad cuya fecha de creación sea menor a la establecida en este parámetro. La fecha debe ir en formatoAAAAMMDDThh:mm:ss+00:00. Los últimos 6 caracteres del formato de la fecha corresponden a la zona horaria (GMT), por lo que deben ser reemplazados por la correspondiente al contexto del cliente.limit: Número máximo de registros a reportar. Debe ser un valor entre 0 y 100. El valor por defecto es 10. Si se especificalimit=0, la respuesta será un archivo CSV descargable en lugar de JSON.order: Los registros son ordenados según la fecha de creación. Este parámetro booleano permite que la búsqueda ocurra de mayor a menor fecha de creación (false) o viceversa (true).last_item: Este parámetro corresponde a la representación json (string) del registro desde el cual se quiere realizar la búsqueda. Este parámetro es útil cuando la búsqueda realizada retorna más registros de los permitidos por el límite, por lo que, si dentro de los elementos retornados no se encuentra el deseado, un nuevo llamado para realizar la búsqueda conservando los parámetros, pero incluyendo este, permitirá hacer que la búsqueda sea realizada desde ellast_itemen adelante.result: El cliente podrá filtrar los registros de actividad por el resultado de la acción registrada. Este parámetro solo puede tomar los valorestrueofalse.tz: Zona horaria para formatear las fechas en la respuesta. Debe estar en formato"+HH:MM"o"-HH:MM"(por ejemplo:"-05:00"para Perú,"+03:00"para Arabia). Si no se especifica, las fechas se retornan en UTC.error_text: Permite filtrar registros que contengan un texto específico en el campomsg(mensaje de error).
Parámetros específicos por grupo
client_id: Permite filtrar por un cliente específico. Aplica a los gruposaccess_logseimg_logs.per_id: Permite filtrar por un identificador de persona específico. Aplica al gruporeniec.process_id: Permite filtrar por un identificador de proceso específico. Aplica a los gruposimg_logs,urlcallbackytelemetry. Es requerido para los gruposurlcallback(cuando se consulta un proceso específico) ytelemetry.
Tipos de grupos de logs
access_logs
Registra los intentos de autenticación y acceso a la API mediante tokens OAuth2.
Propósito: Auditoría de accesos autenticados (login) de los clientes del integrador.
Campos principales en la respuesta:
usr_id: Identificador del usuario propietario de la cuentaclient_id: Identificador del cliente OAuth2 que realizó el accesodate: Fecha y hora del registro (formateada según el parámetrotz)result: Booleano que indica si el acceso fue exitoso (true) o fallido (false)msg: Mensaje descriptivo del resultado (ej:"ok", razón del fallo)resolve_ip: Dirección IP del cliente que realizó la solicituduser_agent: User agent del navegador/cliente
Parámetros de filtro aplicables: client_id, result
reniec
Registra las consultas realizadas al servicio RENIEC (Registro Nacional de Identificación y Estado Civil de Perú) para validación de documentos de identidad peruanos.
Propósito: Auditoría de validaciones de DNI contra la base de datos oficial de RENIEC.
Campos principales en la respuesta:
usr_id: Identificador del usuario propietario de la cuentaper_id: Número de documento de identidad consultadoprocess_id: Identificador del proceso biométrico asociadodate: Fecha y hora del registro (formateada según el parámetrotz)result: Booleano que indica si la consulta fue exitosa (true) o fallida (false)msg: Mensaje descriptivo del resultadodescription: Descripción adicional del procesofec_fin: Timestamp de finalización
Parámetros de filtro aplicables: per_id, result
img_logs
Registra el procesamiento de imágenes (selfies, documentos) durante los procesos de verificación biométrica.
Propósito: Trazabilidad del procesamiento de imágenes capturadas durante los flujos de verificación.
Campos principales en la respuesta:
usr_id: Identificador del usuario propietario de la cuentaclient_id: Identificador del cliente asociadoprocess_id: Identificador del proceso biométricodate: Fecha y hora del registro (formateada según el parámetrotz)email: Email asociado al proceso (si aplica)
Parámetros de filtro aplicables: client_id, process_id
urlcallback
Registra los errores ocurridos al intentar enviar notificaciones (webhooks) a las URLs de callback configuradas por el integrador.
Propósito: Depuración de problemas en la entrega de notificaciones asíncronas.
Campos principales en la respuesta:
usr_id: Identificador del usuario propietario de la cuentasource_id/process_id: Identificador del proceso que generó el callbackdate: Fecha y hora del registromsg: Mensaje de error detallado
Parámetros de filtro aplicables: process_id (requerido para consultas específicas)
Nota
- Únicamente se registran los casos en los que se presentó algún inconveniente durante el envío de la urlcallback.
- Estos registros se conservan por un máximo de 35 días.
- Cuando se consulta con
process_id, se ignoran los filtros de fecha (creation_start,creation_end) yerror_text, y el límite se fija automáticamente en 2 registros.
telemetry
Registra eventos de telemetría y métricas detalladas de los procesos de verificación biométrica.
Propósito: Análisis de rendimiento, seguimiento de eventos y depuración avanzada de procesos.
Campos principales en la respuesta:
process_id: Identificador del proceso (requerido para consultar este grupo)date: Fecha y hora del eventosession_id: Identificador de la sesiónevent_type: Tipo de evento registradointerface_id: Identificador de la interfaz que generó el eventoevent_data: Datos adicionales del evento en formato JSON
Parámetros de filtro aplicables: process_id (requerido)
Importante
El grupo telemetry requiere obligatoriamente el parámetro process_id. No es posible realizar consultas generales sin especificar un proceso.
Formato de respuesta
La API puede retornar los datos en dos formatos según el valor del parámetro limit:
Respuesta JSON (cuando limit > 0 o no especificado)
El backend retornará una colección de registros de actividad coincidentes con la búsqueda en formato JSON.
Estructura de la respuesta:
{
"<nombre_del_grupo>": [
{ /* registro 1 */ },
{ /* registro 2 */ },
...
],
"last_item": { /* objeto para paginación */ } | null
}
- El campo con el nombre del grupo contiene el array de registros encontrados
last_item: Contiene el último elemento de la página actual. Si esnull, indica que no hay más registros. Este valor debe usarse como parámetrolast_itemen la siguiente consulta para obtener la siguiente página.
Códigos de respuesta:
200: Consulta exitosa, todos los resultados fueron retornados206: Consulta exitosa parcial, existen más resultados disponibles (usarlast_itempara continuar)404: No se encontraron registros que coincidan con los criterios de búsqueda
Respuesta CSV (cuando limit = 0)
Cuando se especifica limit=0, la respuesta es un archivo CSV descargable con todos los registros que coincidan con los criterios de búsqueda.
Campos incluidos según el grupo:
access_logs:client_id,date,result,msgreniec:per_id,date,process_id,result,msgimg_logs:client_id,process_id,date,emailtelemetry:process_id,date,session_id,event_type,interface_id,event_data
Ejemplos
Ejemplo 1: Consulta de registros RENIEC
Solicitud:
Tipo de request:\
GETParámetros de la query (URL):
Respuesta (código 200):
Tipo de contenido:\
application/jsonBody:
{ "reniec": [ { "date": "2024-05-31T22:21:11+00:00", "description": "abc", "fec_fin": 1717194074, "msg": "ok", "per_id": "12345678", "process_id": "abc.123.def", "result": true, "usr_id": "abc", "usr_idPer_id": "abc:12345678", "usr_idPer_idResult": "abc:12345678:True", "usr_idResult": "abc:True" } ], "last_item": null }
Ejemplo 2: Consulta de registros de acceso por cliente
Solicitud:
Tipo de request:\
GETParámetros de la query (URL):
Respuesta (código 200):
Tipo de contenido:\
application/jsonBody:
{ "access_logs": [ { "usr_id": "user123", "client_id": "my_client_id_123", "date": "2024-05-31T17:21:11-05:00", "result": true, "msg": "ok", "resolve_ip": "192.168.1.100", "user_agent": "Mozilla/5.0...", "usr_idResult": "user123:True", "usr_idClient_id": "user123:my_client_id_123", "usr_idClient_idResult": "user123:my_client_id_123:True" } ], "last_item": null }
Ejemplo 3: Consulta de telemetría de un proceso específico
Solicitud:
Tipo de request:\
GETParámetros de la query (URL):
Respuesta (código 200):
Tipo de contenido:\
application/jsonBody:
Ejemplo 4: Descarga de registros en formato CSV
Solicitud:
Tipo de request:\
GETParámetros de la query (URL):
Respuesta (código 200):
Tipo de contenido:\
text/csvArchivo descargado:
query.csvContenido del archivo:
Gestión de clientes
El sistema de biometría de TOC Perú permite al integrador gestionar clientes y roles para el control de acceso a los recursos del backend mediante APIs especializadas. Este sistema se basa en el protocolo OAuth 2.0 con tokens JWT, permitiendo una administración granular de permisos a través de scopes específicos.
La gestión de clientes se divide en dos componentes principales:
- Roles: Conjuntos de permisos (scopes) que definen qué operaciones pueden realizarse
- Credenciales de acceso (Clientes): Aplicaciones o usuarios que se autentican con roles asignados
El sistema proporciona trazabilidad completa de todas las operaciones realizadas, registrando quién creó y modificó cada recurso, así como las fechas correspondientes.
APIs de roles
La API /api/roles permite gestionar roles de usuario. Los roles definen conjuntos de scopes (permisos) que pueden asignarse a credenciales de acceso para controlar el acceso a los recursos del sistema.
Método GET
El integrador podrá acceder a sus roles mediante una llamada al endpoint /api/roles con el método GET. Sólo puede ser consumido con un token de acceso que incluya el scope roles:read. Este método retorna una lista paginada de roles del usuario autenticado.
Los parámetros opcionales que se pueden incluir en la búsqueda son los siguientes:
| Parámetro | Tipo | Descripción |
|---|---|---|
rol_nombre |
string | Filtra roles que comiencen con un determinado texto |
limit |
number | Límite de resultados. Rango: 1-100. Valor por defecto: 10 |
last_item |
object | Token de paginación para obtener la siguiente página de resultados |
En base a los parámetros, el backend retornará una colección de roles coincidentes con la búsqueda (completa o incompleta).
Ejemplo de solicitud:
Tipo de request:\
GETHeaders:
Authorization: jwt-bearer aaa.bbb.cccParámetros de la query (URL):
Ejemplo de respuesta (código 200):
Tipo de contenido:\
application/jsonBody:
{ "roles": [ { "rol": "admin", "scopes": ["users:read", "users:write"], "description": "Rol administrativo", "fec_creado": "2023-01-01T00:00:00Z", "fec_editado": "2023-01-01T00:00:00Z", "created": "client_id_creador", "edited": "client_id_editor" } ], "last_item": { "usr_id": "123", "rol": "ultimo_rol" } }
Ejemplo de respuesta (código 206):
Tipo de contenido:\
application/jsonBody:
{ "roles": [ { "rol": "editor", "scopes": ["content:read", "content:write"], "description": "Rol editorial", "fec_creado": "2023-02-01T00:00:00Z", "fec_editado": "2023-02-01T00:00:00Z", "created": "client_id_creador", "edited": "client_id_editor" } ], "last_item": { "usr_id": "123", "rol": "editor" } }
Nota: El código de respuesta 206 (Partial Content) indica que se devuelve una página de resultados y que existen más registros disponibles. El campo last_item contiene el token de paginación que debe incluirse en la siguiente solicitud para obtener la próxima página de resultados.
Propiedades de un rol
En la descripción anterior, se pueden observar las propiedades asociadas a cada rol. A continuación, se detalla el significado de cada una:
rol: Nombre del rolscopes: Lista de permisos asignados al rol que determinan las operaciones permitidasdescription: Descripción del rolfec_creado: Fecha de creación del rol en formato ISO 8601fec_editado: Fecha de última edición del rol en formato ISO 8601created: Identificador del cliente que creó el roledited: Identificador del cliente que editó por última vez el rol
Método POST
El integrador podrá crear un nuevo rol o modificar uno existente mediante una llamada al endpoint /api/roles con el método POST. Sólo puede ser consumido con un token de acceso que incluya el scope roles:write.
Los parámetros que se deben incluir en el body del request son los siguientes:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
rol_nombre |
string | Sí | Nombre del rol. Máximo 128 caracteres. No puede ser root |
scopes |
JSON | Condicional | Lista de scopes en formato JSON. Requerido si se está creando un rol o se desea modificar los scopes. Los scopes no pueden incluir root |
description |
string | Condicional | Descripción del rol. Máximo 200 caracteres. Requerido si se está creando un rol o se desea modificar la descripción |
Validaciones importantes:
- Debe incluir al menos
scopesodescriptionademás derol_nombre - El parámetro
scopesdebe ser una lista válida en formato JSON - Los scopes asignados deben estar dentro de los scopes del cliente que hace la solicitud, excepto si el cliente tiene el scope
security:escape_scopes - No puede ser utilizado para auto-modificar el cliente actual
Ejemplo de solicitud:
Tipo de request:\
POSTx-www-form-urlencodedHeaders:
Authorization: jwt-bearer aaa.bbb.cccContent-Type: application/x-www-form-urlencodedBody:
Ejemplo de respuesta (código 200):
Tipo de contenido:\
text/plainBody:\
ok
Ejemplo de respuesta (código 409):
Tipo de contenido:\
application/jsonBody:
Nota: El código de respuesta 409 (Conflict) se devuelve cuando el rol que se intenta modificar está siendo utilizado activamente por algún cliente. No se puede modificar un rol en estas circunstancias para garantizar la integridad del sistema de permisos.
Método DELETE
El integrador podrá eliminar un rol existente mediante una llamada al endpoint /api/roles con el método DELETE. Sólo puede ser consumido con un token de acceso que incluya el scope roles:delete.
Los parámetros que se deben incluir en el body del request son los siguientes:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
rol_nombre |
string | Sí | Nombre del rol a eliminar. No puede ser root |
Validaciones importantes:
- No se permite eliminar el rol
rootdel sistema - El rol no debe estar asignado a ningún cliente activo
- El cliente debe tener todos los scopes del rol que intenta eliminar, a menos que tenga el scope
security:escape_scopes
Ejemplo de solicitud:
Tipo de request:\
DELETEx-www-form-urlencodedHeaders:
Authorization: jwt-bearer aaa.bbb.cccContent-Type: application/x-www-form-urlencodedBody:
Ejemplo de respuesta (código 200):
Tipo de contenido:\
text/plainBody:\
ok
Ejemplo de respuesta (código 409):
Tipo de contenido:\
application/jsonBody:
Nota: El código de respuesta 409 (Conflict) se devuelve cuando el rol que se intenta eliminar está asignado a uno o más clientes activos. Para eliminar el rol, primero debe removerse de todos los clientes que lo utilicen o dichos clientes deben ser eliminados.
APIs de credenciales de acceso
La API /api/clients permite gestionar credenciales de acceso (clientes OAuth) del integrador. Los clientes pueden ser de tipo bot (aplicaciones) o human (usuarios humanos). Cada cliente cuenta con un client_id y un client_secret que se utilizan para autenticarse con el sistema.
Método GET
El integrador podrá acceder a sus clientes mediante una llamada al endpoint /api/clients con el método GET. Sólo puede ser consumido con un token de acceso que incluya el scope clients:read. Este método retorna una lista paginada de clientes (credenciales de acceso).
Los parámetros opcionales que se pueden incluir en la búsqueda son los siguientes:
| Parámetro | Tipo | Descripción |
|---|---|---|
client_id |
string | Filtra por identificador de cliente específico |
client_name |
string | Filtra clientes cuyo nombre comience con este texto |
rol_nombre |
string | Filtra clientes con roles que comiencen con este texto |
given_name |
string | Filtra por nombre de pila (solo para clientes tipo human) |
family_name |
string | Filtra por apellido (solo para clientes tipo human) |
limit |
number | Límite de resultados. Rango: 0-100. Valor por defecto: 10. Si es 0, devuelve todos los resultados en formato CSV |
last_item |
object | Token de paginación para obtener la siguiente página de resultados |
order |
boolean | Ordenamiento. true: ascendente, false: descendente |
En base a los parámetros, el backend retornará una colección de clientes coincidentes con la búsqueda (completa o incompleta).
Ejemplo de solicitud:
Tipo de request:\
GETHeaders:
Authorization: jwt-bearer aaa.bbb.cccParámetros de la query (URL):
Ejemplo de respuesta (código 200):
Tipo de contenido:\
application/jsonBody:
{ "clients": [ { "client_id": "a1b2c3d4", "client_name": "mi_app", "rol": "admin", "type": "bot", "active": true, "given_name": "Juan", "family_name": "Pérez", "fec_creado": "2023-01-01T00:00:00Z", "fec_exp": "2024-01-01T00:00:00Z" } ], "last_item": { "usr_id": "123", "client_id": "ultimo_cliente" } }
Respuesta en formato CSV (cuando limit=0):
Tipo de contenido:\
text/csvArchivo descargado:
clients.csvContenido del archivo:
Propiedades de un cliente
En la descripción anterior, se pueden observar las propiedades asociadas a cada cliente. A continuación, se detalla el significado de cada una:
client_id: Identificador único del cliente generado automáticamente por el sistemaclient_name: Nombre del clienterol: Rol asignado al cliente que determina sus permisostype: Tipo de cliente. Puede serbot(aplicación) ohuman(usuario humano)active: Estado activo del cliente.trueindica que el cliente puede autenticarse,falseque está deshabilitadogiven_name: Nombre de pila del usuario (solo aplicable para clientes tipohuman)family_name: Apellido del usuario (solo aplicable para clientes tipohuman)fec_creado: Fecha de creación del cliente en formato ISO 8601fec_exp: Fecha de expiración del cliente en formato ISO 8601. Después de esta fecha, el cliente no podrá autenticarse
Método POST
El integrador podrá crear un nuevo cliente o modificar uno existente mediante una llamada al endpoint /api/clients con el método POST. Sólo puede ser consumido con un token de acceso que incluya el scope clients:write.
Los parámetros que se pueden incluir en el body del request son los siguientes:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
client_name |
string | Condicional | Nombre del cliente. Obligatorio para creación |
rol_nombre |
string | Condicional | Nombre del rol a asignar. Obligatorio para creación |
type |
string | Condicional | Tipo de cliente: bot o human. Obligatorio para creación |
given_name |
string | No | Nombre de pila del cliente (recomendado para tipo human) |
family_name |
string | No | Apellido del cliente (recomendado para tipo human) |
password_reset |
string | No | Si es true, restablece el client_secret del cliente |
franja_cron |
string | No | Expresión cron para definir franja horaria permitida de acceso |
franja_duration |
string | No | Duración de la franja horaria en segundos |
active_switch |
string | No | Cambia estado activo. Valores: true o false |
active_switch_undo_date |
string | No | Fecha para revertir automáticamente el cambio de estado (formato ISO 8601) |
expires |
string | No | Fecha de expiración del cliente (formato ISO 8601) |
Validaciones importantes:
- Para crear un cliente: son obligatorios
client_name,rol_nombreytype - Para modificar un cliente: al menos un parámetro debe ser proporcionado además del
client_name - Los tipos válidos son únicamente
botohuman - El cliente debe tener suficientes scopes para asignar el rol especificado
- No puede ser utilizado para auto-modificar el cliente actual
- El formato de las fechas debe ser ISO 8601
Ejemplo de solicitud (crear cliente):
Tipo de request:\
POSTx-www-form-urlencodedHeaders:
Authorization: jwt-bearer aaa.bbb.cccContent-Type: application/x-www-form-urlencodedBody:
Ejemplo de respuesta (código 200 - creación exitosa):
Tipo de contenido:\
application/jsonBody:
Nota importante: El client_secret solo se devuelve al crear un nuevo cliente o al usar password_reset=true. Este valor debe guardarse de forma segura, ya que es la credencial que se utilizará junto con el client_id para autenticarse. No será posible recuperarlo posteriormente.
Ejemplo de solicitud (modificar cliente):
Tipo de request:\
POSTx-www-form-urlencodedHeaders:
Authorization: jwt-bearer aaa.bbb.cccContent-Type: application/x-www-form-urlencodedBody:
Ejemplo de respuesta (código 200 - modificación exitosa):
Tipo de contenido:\
text/plainBody:\
ok
Método DELETE
El integrador podrá eliminar un cliente existente mediante una llamada al endpoint /api/clients con el método DELETE. Sólo puede ser consumido con un token de acceso que incluya el scope clients:write.
Los parámetros que se deben incluir en el body del request son los siguientes:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
client_name |
string | Sí | Nombre del cliente a eliminar |
Validaciones importantes:
- Un cliente no se puede eliminar a sí mismo (auto-eliminación prohibida)
- No se puede eliminar un cliente con rol
root - El cliente debe tener todos los scopes del rol del cliente a eliminar, a menos que tenga el scope
security:escape_scopes
Ejemplo de solicitud:
Tipo de request:\
DELETEx-www-form-urlencodedHeaders:
Authorization: jwt-bearer aaa.bbb.cccContent-Type: application/x-www-form-urlencodedBody:
Ejemplo de respuesta (código 200):
Tipo de contenido:\
text/plainBody:\
ok
Ejemplo de respuesta (código 403):
Tipo de contenido:\
application/jsonBody:
Anexo 1
Tipos de validaciones:
Como se definió anteriormente, el integrador podrá definir qué validaciones se harán sobre los datos de la persona a identificar en cada proceso de validación. Si bien con esto se busca entregar un mayor control al integrador, en el Anexo 2 entregamos una serie de recomendaciones a seguir para robustecer una validación de identidad usando combinaciones de estas validaciones.
liveness:selfie: Esta validación implica que la persona a identificar deberá tomarse una selfie, la cual posteriormente será analizada en una prueba de vida, corroborando (según un umbral) que dicha foto no corresponda a un ataque fraudulento (imagen tomada de una pantalla o foto impresa).liveness:doc:front: Esta validación implica que la persona a identificar deberá tomar una foto a la parte frontal de su documento de identidad, para posteriormente ser analizada en una prueba de fraude, corroborando así (según un umbral) que dicha foto no corresponda a un documento fraudulento (imagen tomada de una pantalla, documento impreso, adulteración de foto de perfil)liveness:doc:back: Esta validación implica que la persona a identificar deberá tomar una foto a la parte trasera de su documento de identidad, para posteriormente ser analizada en una prueba de fraude, corroborando así (según un umbral) que dicha foto no corresponda a un documento fraudulento (imagen tomada de una pantalla, documento impreso, adulteración de foto de perfil)match:ocr:id: Esta validación implica que la persona a identificar deberá tomar una foto a la parte frontal de su documento de identidad, para posteriormente extraer los datos de dicho documento y comprobar que la identidad definida en este coincida con la identidad definida en el proceso de validación.match:mrz:id: Esta validación implica que la persona a identificar deberá tomar una foto de la parte frontal de su documento de identidad, para posteriormente extraer el código MRZ de dicho documento y comprobar que estos coincidan con la identidad definida en el proceso de validación. Este tipo de validación tiene una tasa de falsos negativos menor quematch:ocr:id, pero sólo puede ser utilizada en documentos que cuenten con un código MRZ.match:portrait:selfie: Esta validación implica que la persona a identificar deberá tomarse una selfie junto con una foto de la parte de su documento de identidad que contenga la foto de perfil. Posteriormente, se extraerá la foto de perfil desde el documento y se comparará con la selfie mencionada, corroborando así (según un umbral) que ambas sean coincidentes (match facial).match:db:selfie: Esta validación implica que la persona a identificar deberá tomarse una selfie, la cual posteriormente será contrastada con la base de datos de indexación de rostros dentro del contexto del integrador, corroborando así (según un umbral) que haya una coincidencia entre los rostros de ambas fuentes. Es necesario que el rostro de la persona a identificar haya sido previamente indexado a la base de datos dentro del contexto del integrador.match:ocr:reniec: Esta validación implica que la persona a identificar deberá tomar una foto de la parte frontal de su documento de identidad, para posteriormente extraer los datos de dicho documento y comprobar que estos coincidan con los datos obtenidos de una consulta a RENIEC de la ficha de la persona a identificar. El integrador deberá contar con una trama en RENIEC, con TOC como proveedor de tecnología para realizar la conexión.match:mrz:reniec: Esta validación implica que la persona a identificar deberá tomar una foto de la parte frontal de su documento de identidad, para posteriormente extraer el código MRZ de dicho documento y comprobar que estos coincidan con los datos obtenidos de una consulta a RENIEC de la ficha de la persona a identificar. El integrador deberá contar con una trama en RENIEC, con TOC como proveedor de tecnología para realizar la conexión. Este tipo de validación tiene una tasa de falsos negativos menor quematch:ocr:reniec, pero sólo puede ser utilizada en documentos que cuenten con un código MRZ.match:selfie:reniec: Esta validación implica que la persona a identificar deberá tomarse una selfie, la cual posteriormente será contrastada con la foto de perfil obtenida de una consulta a RENIEC de la ficha de la persona a identificar, comprobando así (según un umbral) que haya una coincidencia entre los rostros de ambas fuentes. El integrador deberá contar con una trama en RENIEC, con TOC como proveedor de tecnología para realizar la conexión.register:face: Esta validación implica que la persona a identificar se deberá tomar una selfie y el proceso deberá contar con el ID de la persona a identificar. Con estos datos, el sistema realizará una indexación en la base de datos del rostro de la persona en el contexto del integrador, quedando registrada para posteriores comprobaciones contra dicha base de datos de rostros indexados por parte del integrador. El registro facial debe ir acompañado de unliveness:selfie.match:pinfo:reniec:gname: La validación permitirá validar los nombres de la persona a identificar que esta misma haya entregado (o entregados por el integrador) contra RENIEC. El integrador deberá contar con una trama en RENIEC, con TOC como proveedor de tecnología para realizar la consulta a dicha fuente.match:pinfo:reniec:fname: La validación permitirá validar los apellidos de la persona a identificar que esta misma haya entregado (o entregados por el integrador) contra RENIEC. El integrador deberá contar con una trama en RENIEC, con TOC como proveedor de tecnología para realizar la consulta a dicha fuente.
Anexo 2
Recomendaciones en la definición de las validaciones
Si bien TOC entrega la flexibilidad para que el integrador personalice las validaciones de los datos de una persona a identificar, recomendamos fuertemente seguir las siguientes indicaciones para dar seguridad a los procesos de validación:
-
Coincidencias entre rostros: Si dentro de las comprobaciones definidas por el integrador se utiliza alguna que involucre un contraste entre la selfie tomada por la persona a identificar y el rostro obtenido desde alguna otra fuente, recomendamos usar dicha validación en conjunto con la validación de prueba de vida de la selfie. De esta manera, el integrador podrá tener mayor certeza de la veracidad de la selfie entregada por la persona a identificar. Ejemplo:
["match:db:selfie", "liveness:selfie"] -
Coincidencias contra datos presentes en el documento de identidad: Si dentro de las comprobaciones definidas por el integrador se utiliza alguna que involucre un contraste entre los datos obtenidos del documento de identidad de la persona a identificar y los datos obtenidos desde alguna otra fuente, recomendamos usar dicha validación en conjunto con la validación de fraude de documento de identidad. De esta manera, el integrador podrá tener mayor certeza de la veracidad de la foto del documento entregada por la persona a identificar. Ejemplo:
["match:ocr:id", "liveness:doc:front"]
Anexo 3
Flujo de datos biométricos entregados
Los datos de un flujo biométrico se entregan de 3 maneras: URL Callback, función callback de SDK, e historial de procesos de identificación. Tanto en la URL callback como en la función callback de SDK se entregan los datos completos de la biometría (esto es, resultado de validación junto a las imágenes capturadas), mientras que los datos entregados por el historial de procesos de identificación (GET a la API /api/id_process) sólo entrega los resultados de la biometría (sin las imágenes capturadas).
graph TD;
A[URL callback / SDK] --> B[Resultado];
A --> C[Imágenes capturadas];
D[Historial] --> B;