Operaciones
El objeto client.operations (OpsManager) proporciona métodos para identificación de huellas, gestión de personas y recuperación de imágenes.
Vista general
Todas las operaciones incluyen automáticamente el número de serie del sensor del escáner e información del dispositivo cuando hay un DriverSocket disponible. Si no se proporciona imageBase64, el SDK utiliza el último resultado de huella capturado por el escáner.
Índice de dedos
Los índices de dedos siguen el mapeo estándar:
Mano izquierda
| Índice | Dedo |
|---|---|
| 0 | Pulgar |
| 1 | Índice |
| 2 | Medio |
| 3 | Anular |
| 4 | Meñique |
Mano derecha
| Índice | Dedo |
|---|---|
| 5 | Meñique |
| 6 | Anular |
| 7 | Medio |
| 8 | Índice |
| 9 | Pulgar |
Identificar persona
Identifica a una persona existente por su huella dactilar. Si la huella coincide con una persona registrada, devuelve su HHID. En ncaso contrario, devuelve un error con código 400.
const result = await client.operations.identifyPerson(
1, // idFinger — índice de dedo
// score e imageBase64 son opcionales; usa el último resultado del escáner si se omiten
);
console.log('Matched HHID:', result.hhid);
En caso de fallo, consultar la documentación relativa a los diferentes tipos de error y los ejemplos de manejo de los mismos, aquí: Manejo de errores
Validar calidad de huella
Existe una funcionalidad isScoreQualityEnough con la que comprobar si la huella tiene la calidad mínima necesaria previo a su envío y no permitir realizar la llamada para verificar huella en tales supuestos.
const isQualityEnough = await client.operations.isScoreQualityEnough(scoreUmbral);
Esta función devuelve true si la calidad es superior al límite pasado como parámetro, y arroja un error en el resto de casos.
Para ello, primero hay que realizar una llamada a getTenantScores para obtener el valor del umbral nfiq2ScoreMin. Lo recomendable es hacer esta llamada tras el login y almacenar el valor para sus usos posteriores en isScoreQualityEnough.
const result = await client.operations.getTenantScores();
// result es el objeto de respuesta de la API:
// result.nfiq2ScoreMin - Umbral de calidad mínima que deberán tener las huellas
scoreUmbral = Number(result.nfiq2ScoreMin);
Se recomienda usar el valor recibido en nfiq2ScoreMin como umbral en el proceso de registro, y la mitad de este como umbral en el proceso de identificación.
Verificar huella
Devuelve un hash temporal para la huella proporcionada, utilizado como entrada al registrar una nueva persona con createPerson. Si la huella ya está registrada, la respuesta también puede incluir el HHID.
const result = await client.operations.checkFingerprint(
1, // idFinger — índice de dedo
// score e imageBase64 son opcionales; usa el último resultado del escáner si se omiten
);
// result es el objeto de respuesta de la API:
// result.id — hash temporal (se pasa a createPerson)
console.log('Hash:', result.id);
Si la huella enviada se encuentra registarada ya para el dedo seleccionado, se recibe un error de código 409 y el HHID asociado a esa huella dentro del objeto del error: error.meta.cause.optionData.
En caso de fallo, consultar la documentación relativa a los diferentes tipos de error y los ejemplos de manejo de los mismos, aquí: Manejo de errores
Crear persona
Registra a una nueva persona con sus datos de huella dactilar. Requiere una lista de hashes obtenida de llamadas previas a checkFingerprint y un indicador de consentimiento.
// 1. Capturar y verificar huellas para construir la lista de hashes
const hash1 = await client.operations.checkFingerprint(1);
const hash2 = await client.operations.checkFingerprint(2);
// 2. Crear persona con los hashes recopilados
const result = await client.operations.createPerson(
[hash1, hash2], // hashList
true, // consentTraining
);
console.log('Created person:', result[0].HHID);
Si entre las huellas enviadas se detectan duplicados, se devuelve un error de codigo 409 y los grupos de dedos (por sus índices) involucrados en esos duplicados.
En caso de fallo, consultar la documentación relativa a los diferentes tipos de error y los ejemplos de manejo de los mismos, aquí: Manejo de errores
Eliminar huella
Elimina una huella de una persona. Si la persona únicamente cuenta con esa huella registrada o todas las demás huellas que tenía registradas fueron borradas previamente, la persona será eliminada también por tanto como consecuencia del borrado de su última huella.
El primer parámetro corresponde al HHID de la persona, y el segundo al identificador interno de la huella (más info)
await client.operations.deleteFingerprint(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 8
);
El HHID se valida como UUID v4 antes de enviar la petición. Se lanza un ConfigError si el formato es inválido.
En caso de fallo, o si el paciente o la huella no existen o han sido ya borrados previamente, el sistema devuelve el error del tipo correspondiente. Consultar la documentación relativa a los diferentes tipos de error y los ejemplo de manejo de los mismo, aquí: Manejo de errores
Eliminar persona
Elimina a una persona y todos sus datos de huella dactilar por HHID.
await client.operations.deletePerson(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
);
El HHID se valida como UUID v4 antes de enviar la petición. Se lanza un ConfigError si el formato es inválido.
En caso de fallo, consultar la documentación relativa a los diferentes tipos de error y los ejemplos de manejo de los mismos, aquí: Manejo de errores
Obtención de imágenes
El acceso a las imágenes de huellas dactilares requiere permisos específicos que deben ser concedidos por Heuristik. Contacta al equipo de Heuristik para solicitar acceso.
| Método | Retorna | Descripción |
|---|---|---|
getFingerprintImageAvailable(hhid) | number[] | Lista de índices de dedos con imágenes almacenadas |
getFingerprintImage(hhid, idFinger) | string | URL prefirmada — usar como <img src> para visualizar en el navegador |
getFingerprintImageRaw(hhid, idFinger) | ArrayBuffer | Datos binarios en bruto — usar para descargar como archivo o procesar en servidor |
getFingerprintImproveImage(hhid, idFinger) | string | URL prefirmada de imagen mejorada — usar como <img src> para visualizar |
getFingerprintImprove(hhid, idFinger) | ArrayBuffer | Datos binarios en bruto (mejorado) — usar para descargar como archivo |
// Listar dedos disponibles
const fingers = await client.operations.getFingerprintImageAvailable(hhid);
// Devuelve un array de índices de dedos que tienen imágenes almacenadas
// ej. [0, 5, 7] → Pulgar izquierdo, Meñique derecho, Medio derecho
// Obtener URL prefirmada (usar directamente como <img src="...">)
const url = await client.operations.getFingerprintImage(hhid, 1);
// Obtener binario BMP en bruto
const buffer = await client.operations.getFingerprintImageRaw(hhid, 1);
const blob = new Blob([buffer], { type: 'image/bmp' });
En caso de fallo, consultar la documentación relativa a los diferentes tipos de error y los ejemplos de manejo de los mismos, aquí: Manejo de errores
Resumen de métodos
| Método | Descripción |
|---|---|
identifyPerson(idFinger, score?, imageBase64?) | Identificar persona por huella dactilar |
getTenantScores | Obtener los umbrales de calidad |
isScoreQualityEnough | Validar si la calidad de la huella está por encima del umbral mínimo |
checkFingerprint(idFinger, score?, imageBase64?) | Obtener hash temporal para registro |
createPerson(hashList, consentTraining) | Registrar nueva persona |
deletePerson(hhid) | Eliminar persona por HHID |
getFingerprintImageAvailable(hhid) | Listar índices de dedos disponibles |
getFingerprintImage(hhid, idFinger) | URL prefirmada para visualizar en navegador |
getFingerprintImageRaw(hhid, idFinger) | Binario en bruto para descargar |
getFingerprintImproveImage(hhid, idFinger) | URL prefirmada de imagen mejorada para visualizar |
getFingerprintImprove(hhid, idFinger) | Binario en bruto de imagen mejorada para descargar |