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 entidad
clientname: Identificador de la credencial que se utilizará para acceder a los recursos del usuario establecidos al momento de crear la credencial. Formato: Correo electrónico
password: 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:\ POST raw

Body:

{
  "username": "bn_qa",
  "clientname": "cred001",
  "password": "11##aa.."
}

Ejemplo de respuesta (código 200):

Tipo de contenido:\ application/json

Body:

{
  "access_token": "aaa.bbb.ccc",
  "expires_in": 3600,
  "scope": "id_process:put id_process:read",
  "token_type": "jwt-bearer"
}

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/text

Body:\ 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
`PER`	`12345678`	Número de identidad nacional Peruano (DNI)
`CHL`	`12345678-9`	Número de identidad nacional Chileno (RUN)
`PERPASS`	`1234567891`	Número de pasaporte peruano
`PERCE`	`123456789123`	Nú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 cabeceras HTTP personalizadas a la solicitud POST. Estas cabeceras deben:

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

{
personal_info:{"given_name":"Nombre1 Nombre2", "family_name":"Apellido1 Apellido2"}
}

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:\ PUT x-www-form-urlencoded

Headers:

Authorization: jwt-bearer aaa.bbb.ccc

Body:

{
  "doc_id": 11111111,
  "nat": "PER",
  "challenges": ["liveness:selfie", "match:db:selfie"],
  "description": "Aplicativo:PCA Canal:WEB Proceso:SVIG",
  "urlCallback": "https://your.domain/login/callback"
}

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/json

Body:
{
  "id": "aaa.111.bbb"
}

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 de manual si el bloqueo se realizó manualmente. De lo contrario, msg comenzará con params:blacklist_id: y continuará con el nombre de la regla de bloqueo.
until: fecha de expiración del bloqueo de la identidad en formato AAAAMMDDThh:mm:ss+00:00.

Ejemplo de respuesta (código 423):

Tipo de contenido:\ application/json

Body:

{
  "msg": "params:blacklist_id:limit",
  "until": "20230613T12:00:00+00:00"
}

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 formato AAAAMMDDThh: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 formato AAAAMMDDThh: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 valores true o false.
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 campo date. 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 de 0: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:\ GET

Parámetros de la query (URL):

{
creation_start: "20230101T12:00:00+00:00",
result: true,
last_item:{"id":"abcxyz", "fecha_creac":" 20230122T11:43:53+00:00"},
description: ["Aplicativo:PCDI"]
}

Ejemplo de respuesta (código 200):

Tipo de contenido:\ application/json

Body:

{
  "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_item en la respuesta. Este valor debe incluirse en el siguiente request utilizando el formato encodeURIComponent.

El procedimiento debe repetirse en cada iteración, enviando el nuevo valor de last_item retornado, hasta que el sistema devuelva un valor null, lo que indicará que no hay más elementos por procesar.

Ejemplo de respuesta (código 200):

Tipo de contenido:\ application/json

Body:

{
  "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 final
challenges: Arreglo que enlista las validaciones realizadas en el proceso de validación
challenges_retries: Diccionario donde se contabiliza el número de intentos por challegen
confidence : El valor mínimo de los confidence de los challenges
date: Fecha de creación del proceso de identificación en formato AAAAMMDDThh: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 datos
doc_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 formato AAAAMMDDThh:mm:ss+00:00.
fec_result: Fecha en la que se resolvió el proceso biométrico en formato AAAAMMDDThh:mm:ss+00:00.
id: Identificador único del proceso de identificación
max_tries : Número de intentos seteado al momento de crear el proceso biométrico
msg: Texto que entrega el motivo del resultado del proceso de validación en caso de que este sea negativo. Ver sección Mensajes de error
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.
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 valor true, quiere decir que el proceso de identificación finalizó con éxito, mientras que un valor false significa que la persona no pudo ser identificada correctamente. Si el valor es null, 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étrico
user-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 formato AAAAMMDDThh: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 formato AAAAMMDDThh: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ámetro per_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 ser PER)

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:\ GET

Parámetros de la query (URL):

{
creation_start: "20230101T12:00:00+00:00",
nat: "PER",
per_id: 012345678,
last_item:{"id":"abcxyz"},
limit: 10
}

Ejemplo de respuesta (código 200):

Tipo de contenido:\ application/json

Body:

{
  "face_db": [
    {
      "date": "20230613T12:00:00+00:00",
      "nat": "PER",
      "per_id": "012345678",
      "face_id": " a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6",
      "process_id": "98uy32h9u4irn"
    }
  ],
  "last_item": null
}

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 formato AAAAMMDDThh: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:\ DELETE x-www-form-urlencoded

Headers:

Authorization: jwt-bearer aaa.bbb.ccc

Body:
{
per_id: "12345678",
nat: "PER"
}

Ejemplo de respuesta (código 200):

Tipo de contenido:\ raw/text

Body:\ 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 (por ejemplo, registros de acceso o registros de consultas a RENIEC, si es que cuenta con este último).

Los parámetros que se deben incluir en el body del request son los siguientes:

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 formato AAAAMMDDThh: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 formato AAAAMMDDThh: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.
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 el last_item en adelante.
group: define el tipo de registros que se retornan. Este parámetro puede tomar los valores access_logs o reniec.
result: el cliente podrá filtrar los registros de actividad por el resultado de la acción registrada. Este parámetro solo puede tomar los valores true o false.

En base a los parámetros, el backend retornará una colección de registros de actividad coincidentes con la búsqueda (completa o incompleta).

Ejemplo de solicitud:

Tipo de request:\ GET

Parámetros de la query (URL):

{
creation_start: "20230101T12:00:00+00:00",
group: "reniec",
last_item:{"usr_id":"abcxyz", "date":12345678},
limit: 10
}

Ejemplo de respuesta (código 200):

Tipo de contenido:\ application/json

Body:

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

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 que match: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 que match: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 un liveness: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;

Mensajes de Error

Cuando se entrega el resultado biométrico al integrador, la propiedad msg proporciona el motivo del error.

Los mensajes de error se agrupan en dos categorías principales: "Procesos Biométricos No Superados" y "Procesos Biométricos No Finalizados".

Identificación No Superada

Estos mensajes indican que la validación biométrica no resultó positiva debido a que uno o varios challenges de identificación no se superaron en los intentos permitidos por el integrador.

Ejemplo 1:

{
  msg: "failed challenges";
}

Nota

Este mensaje se puede visualizar al obtener la información mediante el método GET en el endpoint /api/id_process o mediante el POST enviado a la urlCallback especificada en el momento de al crear el proceso biométrico.

Ejemplo 2:

{
  msg: "Max_tries_exceeded";
}

Nota

Este mensaje se muestra en el front-end cuando se agotan todos los intentos permitidos por el integrador.

Los diferentes tipos de challenges se describen en Anexo 1.

Procesos de Identificación No Finalizados

Estos mensajes se devuelven cuando el proceso de identificación no fue iniciado por la persona o expiró sin concluir todos los challenges del proceso biométrico.

Ejemplo:

{
  msg: "expired";
}

Colección Postman - API de Biometría

Descripción

Se proporciona una colección de Postman que contiene todos los endpoints disponibles del API de Biometría. Esta colección le permitirá probar y validar las diferentes funcionalidades antes de realizar su integración.

Nota

Sugerimos validar el comportamiento de la aplicación utilizando esta colección de Postman. Esto ayudará a identificar si cualquier posible incidencia está relacionada con su implementación o con el servicio.

Recursos Disponibles

Descargar Colección Postman

Nota

Por favor, revise detenidamente la sección de "Recomendaciones" que se encuentra a continuación antes de comenzar a integrar.

Recomendaciones

UrlCallback

Se recomienda verificar los siguientes puntos para asegurar el correcto funcionamiento en su integración:

Firewall o Proxy: Si está utilizando un firewall o proxy, verifique que no se esté generando un bloqueo de tráfico debido a reglas de seguridad que impidan que las solicitudes POST lleguen a su servicio.
Políticas CORS: Si ha configurado políticas CORS en el endpoint establecido como urlCallback, asegúrese de que estas políticas permitan realizar solicitudes POST hacia la urlCallback establecida .
Limitaciones de recepción: Si su urlCallback está diseñado para recibir únicamente ciertos tipos de información con una estructura o tamaño específico, esto podría estar causando que solicitudes POST no sean aceptadas.

Número de intentos

Es recomendable configurar hasta 3 (max_tries: 3) (método PUT) intentos para disminuir la probabilidad de error humano por parte del usuario (por iluminación deficiente, cámara movida, ingreso incompleto de datos etc)

Importante

Configurar esta característica aumenta la probabilidad de completar el flujo exitosamente.

Uso de la cámara

Para los procesos que incluyan desafíos de captura o escaneo de documentos de identidad, se recomienda evitar el uso de cámaras web. Estas cámaras suelen carecer de autofoco, lo que dificulta un registro correcto.

Si el usuario final emplea una cámara web, es recomendable notificarle que debe usar un dispositivo móvil mediante un mensaje emergente o similar. Alternativamente, puede proporcionarse un código QR que permita al usuario continuar el proceso desde un dispositivo móvil.

Importante

No seguir estas recomendaciones puede aumentar significativamente el porcentaje de procesos negativos o expirados.

Ejecución de la creación del proceso biométrico

Los procesos biométricos deben enviarse a los usuarios sin forzar su inicio. La creación e inicio del proceso debe ocurrir en el momento en que el usuario interactúa con el enlace o botón correspondiente.

Si el proceso se crea e inicia automáticamente antes de que el usuario lo abra, existe el riesgo de que este haya expirado cuando el usuario intente completarlo.

Importante

No seguir estas recomendaciones puede aumentar significativamente el porcentaje de procesos negativos o expirados.

Reutilización de Procesos Biométricos Activos

Se recomienda que, en caso de que el sistema del integrador permita acciones como retroceder, actualizar la página, salir, o cualquier otra que pueda resultar en la creación de un nuevo proceso biométrico por parte del cliente final, el sistema del integrador pueda verificar previamente si el cliente ya cuenta con un proceso biométrico activo.

Si existe un proceso biométrico activo, este debe ser reutilizado en lugar de crear uno nuevo.

Importante

La emisión sucesiva de varios procesos biométricos para un mismo usuario provocará que solo uno de esos procesos (el último) sea utilizado. Los procesos no utilizados expirarán y causarán distorsiones en la estadística de uso del sistema.

Obtención de los resultados biométricos

Se recomienda que los resultados biométricos se obtengan a través de la urlCallback (método PUT) o mediante la API GET.

Importante

No se deben obtener resultados desde el front end, ya que esto puede generar riesgos de seguridad de la información.

Integración mediante sdk.

Para garantizar una integración correcta, se debe usar el SDK específico para el sistema operativo correspondiente:

Importante

Recomendamos considerar que los SDKs están diseñados específicamente para garantizar integraciones fluidas y sin problemas con nuestros servicios para los sistemas operativos Android, iOS y los entornos web. TOC no puede dar soporte a integraciones que usen métodos alternativos a los recomendados.