> 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/changelog.md). # Changelog ## \[2.2.1] - 2026-09-23 ### Añadido * Umbrales configurables para la clasificación del estado y las alertas de `GET /api/v1/finger/metrics`: `metrics_saturation_queue_p95_ms`, `metrics_saturation_min_inflight_ratio`, `metrics_error_rate_warning`, `metrics_idle_rps_threshold` y `metrics_quality_alert_window_seconds`. Se configuran en `config.json`, con las variables de entorno `FACEPHI_FINGER_REST_METRICS_*` o en tiempo de ejecución con `POST /api/v1/finger/config`. Un valor no válido o negativo se descarta con un aviso en el log y se usa el de la fuente de menor prioridad. ### Cambiado * La alerta `LOW_QUALITY` tiene en cuenta el tiempo: se desactiva cuando no se observa ninguna extracción de baja calidad durante `metrics_quality_alert_window_seconds` (900 segundos por defecto), aunque la proporción acumulada de extracciones de baja calidad siga por encima del umbral. Su `since` indica el inicio del episodio de baja calidad vigente en lugar de la primera extracción de baja calidad desde el arranque, que sigue publicándose en `quality.summary.lowQualitySince`. * La clasificación `saturated` exige que las peticiones en curso superen estrictamente los hilos configurados, de modo que la propia petición que lee `/metrics` ya no cuenta como trabajo pendiente. ### Corregido * Con una licencia válida, `license.statusMessage` de `GET /api/v1/finger/health` y `state.license.statusMessage` de `GET /api/v1/finger/metrics` muestran `The license is valid.` en lugar de `Unrecognized licensing error code: LF_OK. Please contact support.`. ## \[2.2.0] - 2026-08-20 ### Añadido * Autenticación JWT opcional (HS256) para `POST /api/v1/finger/extract`, `POST /api/v1/finger/authenticate` y `GET|POST /api/v1/finger/config`, configurable en el arranque desde `config.json` o con las variables de entorno `FACEPHI_FINGER_REST_AUTH_*`. `/health`, `/version`, `/metrics`, `/metrics/prometheus` y las peticiones `OPTIONS` no requieren token. `GET /api/v1/finger/config` oculta los ajustes `auth_*` y `POST /api/v1/finger/config` los rechaza. * `GET /api/v1/finger/metrics` publica un snapshot operativo completo: `schemaVersion`, `timestamp`, `service`, `state` (con `classification`), `traffic`, `saturation`, `latency`, `usage`, `quality` y `alerts`. Se mantienen los campos `usageCountersEnabled`, `extractCount`, `authenticateCount` y `totalCount` de la versión 2.1.0. * Endpoint `GET /api/v1/finger/metrics/prometheus`, con el mismo snapshot en formato de exposición Prometheus: las series de nivel HTTP con el prefijo `facephi_` y los bloques propios del servicio (identidad, estado, uso, calidad y alertas) con el prefijo `facephi_finger_`. ### Cambiado * `GET /api/v1/finger/health` devuelve, además de `message`, el campo `initialized` y los bloques `license` (`valid`, `statusCode`, `statusMessage`) y `engine` (`initialized`, `healthy`, `role`, `lastHealthKnown`, `lastHealthCheckAt`, `lastError` y `servicesConfigured`). Cada llamada actualiza el snapshot de salud que publica `GET /api/v1/finger/metrics`. * `POST /api/v1/finger/extract` respeta `options.includeQuality`: con `false`, la respuesta omite `quality` y `qualityDetails`. ### Corregido * En los despliegues en clúster, el valor de `FACEPHI_FINGER_ENGINE_MASTER` se aplica correctamente al descubrimiento de los nodos; si se indica una lista separada por comas, se usa la primera dirección. ## \[2.1.0] - 2026-06-11 ### Añadido * Nuevo endpoint de gestión `GET /api/v1/finger/metrics` que devuelve `usageCountersEnabled`, `extractCount`, `authenticateCount` y `totalCount`. * Conteo de uso condicionado por la licencia para las operaciones `POST /api/v1/finger/extract` y `POST /api/v1/finger/authenticate` completadas con éxito. ### Cambiado * Mejorado el comportamiento de sincronización de los contadores de uso para reducir el desfase entre las métricas del lado del servicio y los valores del panel de licencias. * Actualizada la cobertura de pruebas de integración para validar el comportamiento de las métricas sin depender de temporizaciones frágiles. ### Documentación * Actualizados `README.md`, el OpenAPI, las notas de versión y la documentación técnica para incluir el contrato de `/metrics` y la configuración de contadores de uso. * Documentados los formatos de imagen admitidos para las entradas basadas en imagen en `extract` y `authenticate`: `wsq`, `bmp`, `png`, `jpg`, `jp2`. ## \[2.0.0] - 2026-06-08 ### Cambios incompatibles (Breaking Changes) * Eliminadas las rutas públicas heredadas `POST /api/v1/finger/create-template` y `POST /api/v1/finger/verify`. * Introducido el contrato público 2.0.0 para `POST /api/v1/finger/extract` y `POST /api/v1/finger/authenticate`. * Cambiados los payloads de petición y respuesta de las operaciones de huella dactilar, no compatibles con clientes 1.x.x. ### Añadido * Capa de mapeo de la API pública (`FingerContractMapper`) que traduce el contrato público de Facephi al contrato del backend de procesamiento. * Validación de entrada (codificación Base64, campos obligatorios, nombres de posición, scanType) que devuelve errores HTTP `400`. * Pruebas unitarias para el mapeo de contratos y la validación (`FingerContractMapperTest`). * Aserciones de pruebas de integración que verifican los campos del contrato público, la ausencia de campos específicos de la implementación y las respuestas `404` en las rutas heredadas eliminadas. ### Cambiado * Renombrados los campos de respuesta a: `fingerTemplate`, `quality`, `qualityDetails`, `authStatus`, `similarity`, `sdkDuration`, `queueDuration`. * La validación de `authThreshold` en las peticiones de autenticación es estrictamente de tipo entero (0..100), conforme al contrato público documentado. * Normalizados los mensajes de error HTTP `400` de extract/authenticate/health a un lenguaje orientado a producto. ### Documentación * Renovadas las guías de instalación, técnica y de descripción general para el lanzamiento público 2.0.0. ### Pruebas * Pruebas unitarias: `FingerContractMapperTest`, que cubre el mapeo, la validación y la ausencia de campos internos en todas las respuestas. * Pruebas de integración: colección de Newman actualizada para el contrato público 2.0.0 con aserciones de inspección de stubs y comprobaciones explícitas de las rutas heredadas eliminadas. ## \[1.0.0] - 2026-04-20 ### Añadido * Paquete inicial de documentación pública bajo `doc/`. * Especificación OpenAPI 3.0 para todos los endpoints públicos. * Guías de instalación y de especificaciones técnicas. * Notas de versión para el lanzamiento público inicial del servicio. ### Alcance del servicio * Endpoint de creación de plantillas de huella dactilar. * Endpoint de verificación 1:1 de huella dactilar. * Endpoints de gestión para versión, salud y configuración en tiempo de ejecución. * Precedencia de configuración en tiempo de ejecución con sobrescritura mediante variables de entorno. * Modelo de roles de despliegue master/worker para operación en clúster.