> 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/release_notes/2.2.0_release_notes.md).

# 2.2.0

**Fecha de lanzamiento:** 20 de agosto de 2026

## Descripción general

Facephi Finger Service 2.2.0 añade la autenticación JWT opcional y la observabilidad operativa del servicio: un snapshot completo en `GET /api/v1/finger/metrics`, su exposición Prometheus y una respuesta de `GET /api/v1/finger/health` con el detalle del estado. Los endpoints de operaciones de huella dactilar mantienen el contrato público 2.x.

## Novedades

### Autenticación JWT opcional

* Protege `POST /api/v1/finger/extract`, `POST /api/v1/finger/authenticate` y `GET|POST /api/v1/finger/config` con JWT firmados con HS256 que incluyan el claim `exp`.
* Se configura en el arranque desde `config.json` (`auth_enabled`, `auth_jwt_secret`, `auth_accept_authorization_header`, `auth_accept_api_key_header` y `auth_api_key_header_name`) o con las variables de entorno `FACEPHI_FINGER_REST_AUTH_*`, y está deshabilitada por defecto.
* `/health`, `/version`, `/metrics`, `/metrics/prometheus` y las peticiones `OPTIONS` no requieren token.
* `GET /api/v1/finger/config` oculta estos ajustes y `POST /api/v1/finger/config` los rechaza con HTTP `400`.

### Métricas operativas

* `GET /api/v1/finger/metrics` publica un snapshot con los bloques `schemaVersion`, `timestamp`, `service`, `state`, `traffic`, `saturation`, `latency`, `usage`, `quality` y `alerts`, además de los campos `usageCountersEnabled`, `extractCount`, `authenticateCount` y `totalCount` de la versión 2.1.0.
* `state.classification` resume el snapshot en un único valor (`ok`, `idle`, `degraded`, `saturated`, `unhealthy` o `unknown`) y `alerts` publica las alertas activas.
* El bloque `quality` agrega la calidad de las extracciones y el resultado de las autenticaciones completadas con éxito.
* Nuevo endpoint `GET /api/v1/finger/metrics/prometheus`, con el mismo snapshot en formato de exposición Prometheus.

### Health

* `GET /api/v1/finger/health` devuelve, además de `message`, el campo `initialized` y los bloques `license` y `engine` con el detalle del estado de la licencia y de los componentes de procesamiento. Cada llamada actualiza el snapshot de salud que publica `/metrics`.

### Extracción

* `POST /api/v1/finger/extract` respeta `options.includeQuality`: con `false`, la respuesta omite `quality` y `qualityDetails`.

### Correcciones

* En los despliegues en clúster, el valor de `FACEPHI_FINGER_ENGINE_MASTER` se aplica correctamente al descubrimiento de los nodos.

## Notas de migración

* Las integraciones de 2.1.0 no necesitan cambios, salvo las que envían `"includeQuality": false` y esperaban recibir igualmente `quality` y `qualityDetails`.
* Si habilitas la autenticación JWT, actualiza los clientes de las operaciones de huella dactilar y de `/config` para que envíen un token válido.
* Las sondas que solo leían `message` de `/health` siguen funcionando: `Healthy` o `Unhealthy`.

## Despliegue

```bash
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.2.0

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.2.0
```

## Requisitos

| Componente        | Requisito                          |
| ----------------- | ---------------------------------- |
| Sistema operativo | Linux x86\_64                      |
| Licencia          | Archivo de licencia Facephi válido |
| Docker            | Recomendado para el despliegue     |

## Limitaciones conocidas

* Los endpoints de operaciones de huella dactilar solo están disponibles cuando el servicio se ejecuta en el rol `master`.
* Con una licencia válida, `license.statusMessage` de `/health` muestra `Unrecognized licensing error code: LF_OK. Please contact support.`. Es un mensaje cosmético, corregido en la versión 2.2.1: el campo que indica el estado de la licencia es `license.valid`.
* La configuración JWT se aplica durante el arranque del servicio: cambiarla requiere reiniciar 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)
* [Registro de cambios](/sdks/backend-sdk/finger/changelog.md)

## Soporte

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