> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/api-rest/identity-api/identity-api-reference/shared-biometric-components/authenticate-fingerprint.md). # Authenticate Fingerprint Servicio que realiza la **verificación biométrica de huella dactilar 1:1**, comparando una huella de **probe** contra una huella de **gallery** de la misma posición. Cada lado puede aportarse como **imagen abierta/tokenizada** o como **plantilla biométrica** previamente extraída con [Fingerprint Extraction](/api-rest/identity-api/identity-api-reference/shared-biometric-components/fingerprint-extraction.md), admitiéndose la combinación de ambos formatos. ### Endpoint ``` POST /services/authenticateFingerprint ``` ### Headers | Nombre | Tipo | Requerido | Descripción | | ------------- | ------ | --------- | ------------------------------------------------------------- | | **x-api-key** | string | **Sí** | API key de autorización de acceso. | | **family** | string | No | Valor: **OnBoarding**. Requerido con el servicio de tracking. | {% hint style="info" %} Todas las llamadas a los Endpoints para tracking con **Identity Platform** deben contener el header `family`. {% endhint %} ### Cuerpo de la solicitud **Content-Type:** `application/json` #### Parámetros | Parámetro | Tipo | Requerido | Descripción | | ----------------------------------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `probe` | array | **Sí** | Huella de referencia. Debe contener **exactamente un** elemento. | | `gallery` | array | **Sí** | Huella de comparación. Debe contener **exactamente un** elemento, de la **misma posición** que el `probe`. | | `probe[].position` / `gallery[].position` | integer | **Sí** | Posición del dedo según la numeración NIST (**1–10**). Debe coincidir entre `probe` y `gallery`. | | `probe[].tokenBuffer` / `gallery[].tokenBuffer` | string | Condicional | Imagen de la huella en **Base64** o un **token** de FacePhi. Obligatorio si no se envía `template`. Ver [Formatos aceptados](#formatos-aceptados). | | `probe[].template` / `gallery[].template` | string | Condicional | Plantilla biométrica (Base64) obtenida de `extractFingerprint`. Obligatorio si no se envía `tokenBuffer`. Ver [Formatos aceptados](#formatos-aceptados). | | `threshold` | integer | No | Umbral de decisión. Si se omite, se usa el valor del tenant o el del motor biométrico. | | `tracking` | object | No | Objeto que representa la información de seguimiento necesaria. | | `tracking.extraData` | string | No | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma. | | `tracking.operationId` | string | No | Identificador de operación generado por el SDK Mobile/Web. | {% hint style="info" %} El método de comparación se deriva automáticamente del formato de `probe` y `gallery` (imagen o plantilla). Ver [Especificación de método](#especificación-de-método). {% endhint %} #### Formatos aceptados * **Imagen** (`tokenBuffer`): Base64 de una imagen de huella en `WSQ`, `BMP`, `PNG`, `JPEG` o `JP2`, o un **token** de FacePhi. * **Plantilla** (`template`): el `template` en Base64 devuelto por [`extractFingerprint`](/api-rest/identity-api/identity-api-reference/shared-biometric-components/fingerprint-extraction.md) (huella ya convertida a plantilla biométrica). * **Encoding**: base64 estándar, preferiblemente **sin saltos de línea**. Si llega "wrapped" (saltos CRLF) el servicio lo normaliza antes de procesarlo. #### Especificación de método | Método | Descripción | Entrada | | ------ | --------------------------------------------------------- | ---------------------------------- | | **1** | Autenticación mediante dos **imágenes** | probe: imagen, gallery: imagen | | **2** | Autenticación mediante dos **plantillas biométricas** | probe: template, gallery: template | | **3** | Autenticación mediante una **imagen** y una **plantilla** | probe: imagen, gallery: template | | **4** | Autenticación mediante una **plantilla** y una **imagen** | probe: template, gallery: imagen | #### Ejemplo de solicitud ```json { "probe": [ { "position": 2, "tokenBuffer": "Rk1SACAyMAAAAAEgAAABPAFiAMUAxQEAAAAo..." } ], "gallery": [ { "position": 2, "template": "Rk1SACAyMAAAAAD6AAABPAFiAMUAxQEAAAA..." } ], "threshold": 40, "tracking": { "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` ### Respuestas #### `200` Éxito #### Parámetros de respuesta | Parámetro | Tipo | Descripción | | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------- | | `serviceResultCode` | integer | Código que indica el **resultado general** de la ejecución del servicio. Ver [Service Result Code](#service-result-code). | | `serviceResultLog` | string | Campo descriptivo del resultado de la ejecución del servicio. | | `serviceTime` | string | Tiempo total de procesamiento **(milisegundos)**. | | `serviceTransactionId` | string | Identificador de transacción asociado a la solicitud procesada por la API. | | `serviceFingerprintAuthStatus` | string | Resultado de la coincidencia. Ver [Fingerprint Auth Status](#fingerprint-auth-status). | | `serviceFingerprintScore` | number | Puntuación de similitud entre las dos huellas comparadas. | | `serviceFingerprintThreshold` | number | Umbral de decisión aplicado en la comparación. | #### Service Result Code | serviceResultCode | Descripción | Código HTTP | | ----------------- | ------------------------------------------------------------------------------------ | ----------- | | 0 | La ejecución del servicio fue exitosa, el módulo procesó la solicitud correctamente. | 200 | | -1 | El motor biométrico no pudo completar la comparación (entrada no procesable). | 200 | #### Fingerprint Auth Status | Estado | Descripción | | ---------- | ------------------------------------------------------------------------------------------------ | | `MATCH` | La comparación es positiva: las huellas coinciden. | | `NO_MATCH` | El proceso se ejecutó correctamente pero las huellas no coinciden. | | `ERROR` | No se pudo realizar la comparación (por ejemplo, entrada inválida o no procesable por el motor). | #### Ejemplo de respuesta: MATCH ```json { "serviceResultCode": 0, "serviceResultLog": "match", "serviceTime": "318", "serviceTransactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486", "serviceFingerprintAuthStatus": "MATCH", "serviceFingerprintScore": 62.00000000, "serviceFingerprintThreshold": 40.00000000 } ``` #### Ejemplo de respuesta: NO\_MATCH ```json { "serviceResultCode": 0, "serviceResultLog": "no_match", "serviceTime": "305", "serviceTransactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b", "serviceFingerprintAuthStatus": "NO_MATCH", "serviceFingerprintScore": 12.00000000, "serviceFingerprintThreshold": 40.00000000 } ``` #### `400` Bad Request ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [] } ``` #### `401` Unauthorized ```json { "message": "Unauthorized" } ``` #### `403` Forbidden ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Bad Gateway ```json { "status": 502, "title": "Bad Gateway", "detail": "Server got an invalid response.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### `504` Gateway Timeout ```json { "message": "Endpoint request timed out" } ```