Guía de integración de biometría - SDK Web Identia

El SDK Web de Identia se distribuye como una biblioteca de JavaScript disponible desde un CDN. Este documento describe los pasos necesarios para integrar el SDK en tu aplicación web.

Primeros Pasos

Para comenzar la integración, incluye el SDK en tu aplicación web añadiendo la siguiente etiqueta <script> a tu HTML:

<script src="https://userintegration.apifacialdev.identia.pe/identia.biometria.min.js"></script>

MD5: 01f309b775928a801dc587808f570c26

Importante

La URL proporcionada no debe ser modificada, ya que es la misma para todos los ambientes, ya sea QA o Producción.

Inicialización

Después de incluir el SDK, necesitas inicializarlo especificando un elemento div en el que se mostrará la interfaz de usuario, el ID del proceso de validación (obtenido de las APIs), una función de callback para recibir los datos de la biometría, y el ambiente del sistema biométrico sobre el cual estés trabajando.

Sintaxis

IdentiaVerification(
  document.getElementById("biometria"),
  "aa.12.bb",
  handler_function,
  "dev"
);

Parámetros

Parámetro	Tipo	Descripción	Valores posibles	Obligatorio
`element`	`HTMLElement`	Elemento DOM donde se renderizará la interfaz del SDK.	Cualquier `<div>` válido	Sí
`processId`	`String`	ID del proceso de validación obtenido de las APIs.	Formato: `aa.12.bb`	Sí
`callback`	`Function`	Función que se invocará con los datos biométricos al completar el proceso.	Función JavaScript válida	Sí
`environment`	`String`	Ambiente del sistema biométrico.	`"dev"`, `"qa"`, `"prod"`	Sí
`styleId`	`String`	ID de personalización gráfica obtenido del Backoffice (opcional, usar con sufijo `&v=2a`).	ID de personalización	No

Ejemplo básico

Por ejemplo, si tienes un elemento div con el ID biometria, si el ID del proceso de validación entregado por las APIs es aa.12.bb y una función de callback llamada handler_function, puedes inicializar el SDK de la siguiente manera:

IdentiaVerification(
  document.getElementById("biometria"),
  "aa.12.bb",
  handler_function,
  "dev"
);

Importante

Al inicializar el SDK, asegúrate de especificar el ambiente correcto. En el ejemplo anterior, se utiliza "dev" para un ambiente de desarrollo. Si estás trabajando en un ambiente de QA, reemplaza "dev" por "qa". Si el ambiente es de Producción, utiliza "prod".

Esto iniciará el proceso biométrico dentro del elemento <div> especificado en tu página web.

Personalización gráfica

Si has creado una personalización de la interfaz en el Backoffice, puedes agregarla mediante el parámetro styleId con el sufijo &v=2a. Simplemente agrega el ID de tu personalización como valor de este parámetro de la siguiente manera:

IdentiaVerification(
  document.getElementById("biometria"),
  "aa.12.bb",
  handler_function,
  "dev",
  styleId
);

Manejo de Datos Biométricos

Función de callback

A continuación, se muestra un ejemplo de cómo podría verse tu función de callback (funcion_handler). Esta función será invocada con los datos biométricos al completar el proceso biométrico:

function funcion_handler(data_biometrica) {
  if (data_biometrica.result) {
    console.log("Process successful");
  } else {
    console.log("Process unsuccessful", data_biometrica.msg);
  }
}

Reemplaza "aa.12.bb" con tu verdadero ID de proceso de identificación y funcion_handler con el nombre real de tu función de callback.

Estructura de respuesta

Los datos retornados del proceso biométrico estarán estructurados de la siguiente manera:

Campo	Tipo	Descripción
`result`	`Boolean`	Indica si el proceso biométrico fue exitoso (`true`) o no (`false`).
`msg`	`String`	El mensaje de error asociado con el proceso biométrico cuando `result` es `false`. Los diferentes tipos de `msg` se describen en la sección de mensajes de error.
`confidence`	`Number`	El nivel de confianza del proceso biométrico (valor entre 0 y 1).
`process_data`	`Object`	Los datos biométricos que fueron capturados asociados con el proceso biométrico.
`description`	`String`	Descripción adicional del proceso.
`id`	`String`	ID único del proceso de validación.
`minimal_response`	`Boolean`	Indica si la respuesta es mínima o completa.
`require`	`Any`	Requisitos adicionales (si aplica).
`urlRedirect`	`String`	URL de redirección (si aplica).

Ejemplo de respuesta no exitosa

Ejemplo de los datos biométricos cuando el proceso es no exitoso:

{
   result: false,
   msg: "liveness:selfie",
   confidence: 1
}

Ejemplo de respuesta exitosa

Ejemplo de los datos biométricos cuando el proceso es exitoso:

{
  "result": true,
  "msg": "success",
  "confidence": 0.8984457,
  "description": "",
  "id": "aaaa.bbbb.ccc",
  "minimal_response": false,
  "process_data": {
    "ocr": "",
    "personal_info": {
      "doc_type": "",
      "family_name": "",
      "given_name": "",
      "id": "11111111",
      "nat": "PER"
    },
    "selfie": "base64encodedstring",
    "doc": {
      "front": "base64encodedstring",
      "back": "base64encodedstring"
    }
  },
  "require": null,
  "urlRedirect": null
}

Campos de `process_data`

Campo	Tipo	Descripción
`ocr`	`String`	Datos de OCR extraídos del documento.
`personal_info`	`Object`	Información personal del usuario.
`personal_info.doc_type`	`String`	Tipo de documento de identidad.
`personal_info.family_name`	`String`	Apellido(s) del usuario.
`personal_info.given_name`	`String`	Nombre(s) del usuario.
`personal_info.id`	`String`	Número de documento de identidad.
`personal_info.nat`	`String`	Nacionalidad (código de país).
`selfie`	`String`	Imagen de selfie codificada en BASE64.
`doc.front`	`String`	Imagen del anverso del documento codificada en BASE64.
`doc.back`	`String`	Imagen del reverso del documento codificada en BASE64.

Nota

La información puede variar según los challenges configurados al momento de crear el proceso biométrico.
Para garantizar la máxima seguridad en su implementación, le sugerimos encarecidamente no obtener las imágenes del usuario directamente desde el frontend. En su lugar, recomendamos utilizar la urlCallback, ya que esta proporciona una comunicación segura de backend a backend, protegiendo así la integridad de los datos biométricos.

Mensajes informativos durante la validación biométrica

El sistema genera mensajes informativos durante la validación biométrica que pueden ser utilizados por los integradores para obtener información de lo que ocurre en el momento en que el usuario final interactúa con el API de biometría.

Características:

Estos mensajes se emiten a través de la función handler del SDK.
Pueden ser capturados por las integraciones para generar indicadores sobre los eventos que ocurren durante los procesos biométricos.
No son de uso obligatorio.

Mensajes generados

Mensaje	Motivo
`selfie:sdk:connection:timeout`	Tiempo de espera excedido durante la operación
`selfie:sdk:camera:empty`	El dispositivo no cumple con los requisitos mínimos de hardware
`selfie:sdk:camera:overconstrained`
`selfie:sdk:camera:Access`	No hay acceso o permisos necesarios para usar la cámara
`selfie:sdk:camera:busy`
`selfie:sdk:camera:abort`
`selfie:sdk:bug`
`selfie:sdk:unknown`	Error no identificado del sistema
`ui:connection:error`	La conexión con internet se interrumpió o es inestable
`process:response:connection:error`
`process:response:connection:timeout`

Otros mensajes relacionados

Mensaje	Motivo
`selfie:assets:timeout`	Este mensaje aparece cuando no cargan todos los recursos que el usuario necesita para pasar por su proceso biométrico en el dispositivo.

Mensajes de Error

Cuando el resultado biométrico se entrega al integrador, la propiedad msg contendrá la causa del error si hay un resultado negativo.

Los diferentes tipos de msg se agrupan en dos categorías: "procesos de identificación no finalizados" e "identificación no superada".

Identificación No Superada

Este grupo de errores se devuelve cuando el proceso de identificación es infructuoso debido a que no se superó uno de los desafíos (challenges) de identificación.

El msg corresponderá al desafío de identificación fallido.

Ejemplo 1:

{
  msg: "liveness:selfie"
}

Razón: El desafío liveness:selfie no se superó porque el selfie no cumple con el umbral mínimo para la detección de vida.

Ejemplo 2:

{
  msg: "match:ocr:id"
}

Razón: El desafío match:ocr:id no se superó porque el OCR del ID no coincide con el valor esperado.

Los diferentes tipos de challenges se describen en la documentación de la API.

Procesos de Identificación No Finalizados

Este grupo de errores se devuelve cuando el proceso de identificación es infructuoso debido a un error en el análisis de los datos biométricos.

Valor de `msg`	Descripción
`no reniec_portrait data`	Los datos obtenidos de RENIEC no incluyen el retrato. Ajusta los desafíos a los datos retornados por RENIEC.
`no reniec data`	No se pudieron obtener los datos de RENIEC. Verifica tu configuración y/o contrato con RENIEC.
`selfie not found`	Falta el selfie en los datos biométricos. Podría ser un error del dispositivo del usuario final. Contacta al soporte.
`no reniec params`	Tus parámetros de RENIEC aún no están configurados. Revisa tu configuración en el backoffice de tu cuenta.
`no back doc data`	Falta el dato del reverso del documento de identidad en los datos biométricos. Podría ser un error del dispositivo del usuario final. Contacta al soporte.
`no front doc data`	Falta el dato del anverso del documento de identidad en los datos biométricos. Podría ser un error del dispositivo del usuario final. Contacta al soporte.
`doc_type not found`	El tipo de documento de identidad no existe.
`doc not found`	Falta el documento de identidad en los datos biométricos. Podría ser un error del dispositivo del usuario final. Contacta al soporte.
`wrong challenge {$challenge}`	Uno de los desafíos proporcionados no es válido.
`db_write`	Error interno. El sistema biométrico podría estar experimentando un problema temporal y no se pudo analizar el proceso de ID.

Ambientes

Al inicializar el SDK, asegúrate de especificar el ambiente correcto como el cuarto parámetro.

Ambiente	Valor	Descripción
Desarrollo	`"dev"`	Ambiente para desarrollo y pruebas iniciales.
QA	`"qa"`	Ambiente de control de calidad para pruebas.
Producción	`"prod"`	Ambiente de producción para uso final.

Reemplaza "dev" por el identificador de tu ambiente objetivo.

Recomendaciones

Permissions-Policy

Si tiene políticas de seguridad en este sentido, debe agregar los orígenes de identia.pe, como se muestra a continuación en el ejemplo:

Permissions-Policy: camera=(self "https://*.identia.pe"), geolocation=(self "https://*.identia.pe")

Esta configuración permite el uso de la cámara y la geolocalización en su aplicación web únicamente desde el dominio identia.pe y sus subdominios. Asegúrese de ajustar estos parámetros según sus necesidades de seguridad y privacidad.

Integración mediante SDK nativo

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

Plataforma	Enlace a documentación
Android	Documentación SDK Android
iOS	Documentación SDK iOS

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. Es importante considerar que TOC no puede dar soporte a integraciones que usen métodos alternativos a los recomendados.

Guía de integración de biometría - SDK Web Identia

Primeros Pasos

Inicialización

Sintaxis

Parámetros

Ejemplo básico

Personalización gráfica

Manejo de Datos Biométricos

Función de callback

Estructura de respuesta

Ejemplo de respuesta no exitosa

Ejemplo de respuesta exitosa

Campos de process_data

Mensajes informativos durante la validación biométrica

Mensajes generados

Otros mensajes relacionados

Mensajes de Error

Identificación No Superada

Procesos de Identificación No Finalizados

Ambientes

Recomendaciones

Permissions-Policy

Integración mediante SDK nativo

Campos de `process_data`