> 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/sdks/backend-sdk/finger.md).

# Finger Service

API REST de huella dactilar para la extracción de plantillas y la autenticación 1:1.

## Aviso importante de compatibilidad

IMPORTANTE - CAMBIO INCOMPATIBLE (BREAKING CHANGE) (2.0.0)

A partir de la versión 2.0.0, los endpoints de operaciones de huella dactilar no son compatibles con la versión 1.x.x:

* `POST /api/v1/finger/extract`
* `POST /api/v1/finger/authenticate`

Las rutas públicas heredadas `POST /api/v1/finger/create-template` y `POST /api/v1/finger/verify` no están disponibles en la versión 2.0.0.

Los formatos de payload de petición y respuesta han cambiado. Las integraciones creadas para la versión 1.x.x deben migrar al contrato público 2.0.0 antes de actualizar.

## Descripción general

Facephi Finger Service expone una API pública bajo `/api/v1/finger/` con nombres de campo orientados a huella dactilar como `image`, `position`, `fingerTemplate`, `authStatus` y `similarity`.

Opcionalmente se puede proteger los endpoints públicos de huella dactilar y de gestión mediante autenticación JWT. Se configura al inicio del servicio a partir de `config.json` o de las variables de entorno `FACEPHI_FINGER_REST_*`.

Para las peticiones que incluyen imágenes de huella dactilar (`image`, `image1`, `image2`), los formatos admitidos son `wsq`, `bmp`, `png`, `jpg` y `jp2`.

El servicio proporciona:

* Extracción de plantillas de huella dactilar
* Autenticación 1:1 de huella dactilar
* Contadores de uso mediante `GET /api/v1/finger/metrics`
* Endpoints de salud, versión y configuración en tiempo de ejecución

## Contrato público

### Extract

Formatos de imagen admitidos para `image`: `wsq`, `bmp`, `png`, `jpg`, `jp2`.

Petición:

```json
{
  "image": "<base64_fingerprint_image>",
  "position": "RightIndex",
  "options": {
    "dpi": 500,
    "scanType": "Plain",
    "includeQuality": true
  }
}
```

Respuesta:

```json
{
  "fingerTemplate": "<base64_generated_template>",
  "position": "RightIndex",
  "scanType": "Plain",
  "quality": 88,
  "qualityDetails": {
    "nfiq2": 79.0,
    "nfiq": 1.0,
    "score": 88.0
  },
  "sdkDuration": 123,
  "queueDuration": 2
}
```

### Metrics

Respuesta:

```json
{
  "usageCountersEnabled": true,
  "extractCount": 12,
  "authenticateCount": 7,
  "totalCount": 19
}
```

Notas:

* `usageCountersEnabled` depende de la clave de metadatos de licencia `ActivateUsageCounters`.
* `extractCount` y `authenticateCount` se corresponden con los atributos de medición de licencia `FingerExtractCounter` y `FingerAuthenticateCounter`.
* `totalCount` se calcula como `extractCount + authenticateCount`.

### Authenticate

Formatos de imagen admitidos para `image1` e `image2`: `wsq`, `bmp`, `png`, `jpg`, `jp2`.

Petición usando plantillas:

```json
{
  "fingerTemplate1": "<base64_probe_template>",
  "fingerTemplate2": "<base64_gallery_template>",
  "position": "RightIndex",
  "options": {
    "authThreshold": 20
  }
}
```

Petición usando imágenes:

```json
{
  "image1": "<base64_probe_image>",
  "image2": "<base64_gallery_image>",
  "position": "RightIndex",
  "options": {
    "authThreshold": 20
  }
}
```

Respuesta:

```json
{
  "authStatus": "Positive",
  "similarity": 84.65,
  "sdkDuration": 131,
  "queueDuration": 1
}
```

## Endpoints de la API

| Endpoint                      | Método   | Propósito                                                              |
| ----------------------------- | -------- | ---------------------------------------------------------------------- |
| `/api/v1/finger/extract`      | POST     | Extrae una plantilla de huella dactilar a partir de un payload público |
| `/api/v1/finger/authenticate` | POST     | Ejecuta la autenticación pública 1:1 de huella dactilar                |
| `/api/v1/finger/metrics`      | GET      | Obtiene el informe de contadores de uso                                |
| `/api/v1/finger/version`      | GET      | Versión del servicio y estado de la licencia                           |
| `/api/v1/finger/health`       | GET      | Comprobación de salud y disponibilidad del servicio                    |
| `/api/v1/finger/config`       | GET/POST | Obtiene o actualiza la configuración en tiempo de ejecución            |

## Inicio rápido

### Requisitos

| Componente | Requisito                          |
| ---------- | ---------------------------------- |
| SO         | Linux x86\_64                      |
| Runtime    | Se recomienda Docker               |
| Licencia   | Archivo de licencia Facephi válido |

### Despliegue con Docker

```bash
docker run -d \
  -p 6982:6982 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name finger-service \
  facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.1.0
```

### Verificar el despliegue

```bash
curl http://localhost:6982/api/v1/finger/health
curl http://localhost:6982/api/v1/finger/version
```

Respuestas típicas:

```json
{ "message": "Healthy" }
```

```json
{ "message": "2.1.0 Copyright (c) 2026 FacePhi Biometria. All rights reserved." }
```

Cuando la autenticación JWT está habilitada, `health` y `version` permanecen públicos mientras que los endpoints protegidos requieren un JWT válido.

## Configuración

Crea `/app/config/config.json`:

```json
{
  "port": 6982,
  "number_of_threads": 1,
  "connection_timeout": 60,
  "keep_alive_request_number": 0,
  "client_max_body_size": 100,
  "logger_level": "info",
  "logger_path": "/app/logs",
  "logger_rotation": "daily",
  "logger_max_files": 7,
  "auth_enabled": false,
  "auth_jwt_secret": "",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key",
  "engine_connection_timeout": 10000,
  "engine_request_timeout": 60000,
  "engine_max_retries": 3,
  "engine_retry_delay": 1000,
  "engine_verify_ssl": false,
  "engine_verbose": false,
  "engine_pool_size": 4,
  "engine_url": "http://localhost:8080"
}
```

La configuración JWT se aplica durante el arranque del servicio. Si actualizas estos valores, reinicia el servicio.

## Documentación

* [Guía de instalación](/sdks/backend-sdk/finger/installation/installation_instructions.md)
* [Especificaciones técnicas](/sdks/backend-sdk/finger/technical_documentation/technical_specifications.md)
* [Referencia de la API](https://github.com/facephi/facephi-gitbook-docs/tree/master/docs/sdks/backend-sdk/finger/technical_documentation/openapi.yaml)
* [Registro de cambios](/sdks/backend-sdk/finger/changelog.md)

## Nota sobre la abstracción del proveedor

La documentación y los payloads públicos mantienen intencionadamente abstraído el runtime de procesamiento. Las integraciones deben apoyarse únicamente en el contrato público de Facephi documentado.

## Soporte

Para licencias y soporte técnico, contacta con tu representante de Facephi.