> 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/fingerprint-extraction.md).

# Fingerprint Extraction

Servicio que realiza la **captura y extracción de plantillas biométricas de huella dactilar** a partir de imágenes de huella, abiertas o tokenizadas. Cada imagen se convierte en una plantilla (`template`) reutilizable en el servicio de autenticación de huella.

{% hint style="warning" %}
Tenga en cuenta que los valores de calidad retornados son estimaciones basadas en la imagen de huella proporcionada. La precisión y confiabilidad reales pueden variar dependiendo de la calidad y características de la imagen de entrada.
{% endhint %}

### Endpoint

```
POST /services/extractFingerprint
```

### 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. |

### Cuerpo de la solicitud

**Content-Type:** `application/json`

#### Parámetros

| Parámetro               | Tipo    | Requerido | Descripción                                                                                                             |
| ----------------------- | ------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
| `fingers`               | array   | **Sí**    | Lista de huellas a procesar. Se admiten de **1 a 10** huellas por solicitud (configurable por tenant).                  |
| `fingers[].position`    | integer | **Sí**    | Posición del dedo según la numeración NIST (**1–10**). Ver [Posiciones de dedo](#posiciones-de-dedo).                   |
| `fingers[].tokenBuffer` | string  | **Sí**    | Imagen de la huella en **Base64** o un **token** de FacePhi. Ver [Formatos aceptados](#formatos-aceptados-tokenbuffer). |
| `fingers[].dpi`         | integer | No        | Resolución de la imagen en puntos por pulgada. Si se omite, se usa el valor por defecto del tenant (500).               |
| `fingers[].scanType`    | string  | No        | Tipo de captura (`Plain` por defecto). Ver [Tipos de captura](#tipos-de-captura-scantype).                              |

#### Posiciones de dedo

| Posición | Dedo        | Posición | Dedo       |
| -------- | ----------- | -------- | ---------- |
| 1        | RightThumb  | 6        | LeftThumb  |
| 2        | RightIndex  | 7        | LeftIndex  |
| 3        | RightMiddle | 8        | LeftMiddle |
| 4        | RightRing   | 9        | LeftRing   |
| 5        | RightLittle | 10       | LeftLittle |

#### Formatos aceptados (tokenBuffer)

El campo `tokenBuffer` admite una imagen de huella codificada en **Base64**, o un **token** de FacePhi (referencia tokenizada que el servicio resuelve internamente).

Formatos de imagen soportados por el motor:

| Formato | Descripción                                                                                           |
| ------- | ----------------------------------------------------------------------------------------------------- |
| `WSQ`   | Wavelet Scalar Quantization (estándar de huella dactilar; formato habitual de los widgets de captura) |
| `BMP`   | Bitmap                                                                                                |
| `PNG`   | Portable Network Graphics                                                                             |
| `JPEG`  | JPEG                                                                                                  |
| `JP2`   | JPEG 2000 (contenedor `.jp2` o codestream)                                                            |

**Encoding**: base64 estándar. Se recomienda enviarlo **sin saltos de línea**; si la imagen viene con base64 "wrapped" (saltos CRLF), el servicio los normaliza automáticamente. El `template` devuelto en la respuesta es **base64 de una sola línea**.

#### Tipos de captura (scanType)

| Valor    | Descripción                                      | Soporte (versión actual)                     |
| -------- | ------------------------------------------------ | -------------------------------------------- |
| `Plain`  | Captura plana / en vivo (dedo apoyado plano)     | **Soportado** (valor por defecto)            |
| `Rolled` | Captura rodada (el dedo se rueda de lado a lado) | Requiere una imagen capturada en modo rodado |
| `Latent` | Huella latente / forense                         | Requiere una imagen latente                  |

* Si se omite, se usa `Plain`.
* El `scanType` debe corresponder al tipo de imagen enviada. Para la captura estándar de onboarding (incluida la del widget) usar **`Plain`**.
* Si el motor no puede generar el template con el modo indicado (por ejemplo, una imagen plana enviada como `Rolled`/`Latent`), el servicio responde **`400`** con el mensaje del motor (p. ej. `"Finger template creation failed"`), no un `502`.

#### Ejemplo de solicitud

```json
{
  "fingers": [
    {
      "position": 2,
      "tokenBuffer": "Rk1SACAyMAAAAAEgAAABPAFiAMUAxQEAAAAo...",
      "dpi": 500,
      "scanType": "Plain"
    }
  ]
}
```

### 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.                                           |
| `serviceResultLog`     | string  | Campo descriptivo del resultado o mensaje de error, si aplica.                                                     |
| `serviceTime`          | string  | Tiempo total de procesamiento **(milisegundos)**.                                                                  |
| `serviceTransactionId` | string  | Identificador de transacción asociado a la solicitud procesada por la API.                                         |
| `templates`            | array   | Lista de plantillas extraídas, una por cada huella enviada. Ver [Campos de la plantilla](#campos-de-la-plantilla). |

#### Campos de la plantilla

| Campo            | Tipo    | Descripción                                                                                     |
| ---------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `position`       | integer | Posición del dedo (1–10) correspondiente a la plantilla.                                        |
| `template`       | string  | Plantilla biométrica extraída, codificada en Base64. Reutilizable en `authenticateFingerprint`. |
| `overallQuality` | integer | Calidad global de la huella.                                                                    |
| `nfiq2`          | number  | Puntuación de calidad **NFIQ 2.0**.                                                             |
| `nfiq`           | number  | Puntuación de calidad **NFIQ**.                                                                 |
| `quality`        | number  | Puntuación de calidad del motor biométrico.                                                     |
| `dpi`            | integer | Resolución utilizada para procesar la huella.                                                   |
| `scanType`       | string  | Tipo de captura procesado (`Plain`, `Rolled`, `Latent`).                                        |

#### Service Result Code

El `serviceResultCode` indica el resultado general de la ejecución del servicio:

| serviceResultCode | Descripción                                                                          | Código HTTP |
| ----------------- | ------------------------------------------------------------------------------------ | ----------- |
| 0                 | La ejecución del servicio fue exitosa, el módulo procesó la solicitud correctamente. | 200         |

#### Ejemplo de respuesta

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "Service request successfully processed",
  "serviceTime": "742",
  "serviceTransactionId": "b2f6297b-01ca-4aa3-afd7-6cb3c9d74141",
  "templates": [
    {
      "position": 2,
      "template": "Rk1SACAyMAAAAAD6AAABPAFiAMUAxQEAAAA...",
      "overallQuality": 82,
      "nfiq2": 78.0,
      "nfiq": 2.0,
      "quality": 0.91,
      "dpi": 500,
      "scanType": "Plain"
    }
  ]
}
```

#### `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"
}
```