> 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/technical_documentation/technical_specifications.md). # Especificaciones técnicas ## Aviso de compatibilidad IMPORTANTE - CAMBIO INCOMPATIBLE (BREAKING CHANGE) (2.0.0) El contrato de payload REST para las operaciones de huella dactilar cambió en la versión 2.0.0 y no es compatible con los payloads de cliente 1.x.x. ## Requisitos mínimos | Componente | Requisito | | ---------- | --------------------- | | SO | Linux x86\_64 | | CPU | 4 núcleos | | Memoria | 4 GB de RAM | | Disco | 2 GB de espacio libre | ## Recomendado para producción | Componente | Recomendación | | -------------- | --------------------------------------------------------- | | SO | Ubuntu LTS | | CPU | 8 o más núcleos | | Memoria | 8 GB o más de RAM | | Almacenamiento | SSD para logs y capas del contenedor | | Red | Conectividad de baja latencia entre los nodos del clúster | ## Restricciones de runtime y compilación * Arquitectura compatible: x86\_64 * Sistema operativo objetivo compatible: Linux * Runtime base del contenedor: Ubuntu 20.04 * Puertos expuestos por la imagen: `6982` (API REST) y `47500`-`47509` (comunicación entre los nodos del clúster) ## Arquitectura del servicio El servicio actúa como una capa de adaptación de API REST sin estado: Aplicación cliente -> Facephi Finger Service -> Procesamiento de huella dactilar de Facephi Características: * No se almacena estado de sesión en la capa de API * Las peticiones públicas se validan y normalizan antes de procesarse * Las respuestas de procesamiento se traducen de nuevo al contrato público * El procesamiento puede escalarse con una topología de clúster: un nodo `master` que recibe las peticiones y varios nodos `worker` que aportan capacidad de procesamiento ## Disponibilidad de endpoints por rol | Rol | Endpoints | | -------- | ----------------------------------------------------------------------------------------- | | `master` | `extract`, `authenticate`, `health`, `version`, `metrics`, `metrics/prometheus`, `config` | | `worker` | `health`, `version`, `metrics`, `metrics/prometheus`, `config` | En un nodo `worker`, `POST /api/v1/finger/extract` y `POST /api/v1/finger/authenticate` responden HTTP `404`. ## Formatos de imagen admitidos (endpoints públicos de huella dactilar) Para peticiones basadas en imagen en: * `POST /api/v1/finger/extract` (`image`) * `POST /api/v1/finger/authenticate` (`image1`, `image2`) los formatos de imagen de huella dactilar admitidos son: * `wsq` * `bmp` * `png` * `jpg` * `jp2` Las imágenes y las plantillas se envían codificadas en Base64 (RFC 4648). La resolución de las imágenes se indica con `options.dpi`, entre `250` y `1000` puntos por pulgada (`500` por defecto). ## Modelo de configuración ### Orden de precedencia De mayor a menor prioridad: 1. Variables de entorno (`FACEPHI_FINGER_REST_*` y `FACEPHI_FINGER_ENGINE_*`) 2. `config.json` 3. Valores por defecto del servicio ### Grupos de configuración en tiempo de ejecución * Ajustes del servidor REST: puerto de escucha, hilos, timeouts, tamaño de body, logging, recogida de métricas * Ajustes de autenticación REST: habilitación de JWT, secreto HS256, cabeceras de token aceptadas * Ajustes de procesamiento: URL, timeout de conexión/petición, reintentos, tamaño del pool, verificación SSL * Ajustes de topología: rol (`master`/`worker`), lista de servicios de procesamiento, dirección del nodo `master` (solo variables de entorno) * Umbrales de las métricas operativas: clasificación del estado y alertas de `GET /api/v1/finger/metrics` * Contadores de uso: dependen de la licencia Los ajustes de autenticación JWT y de topología se aplican durante el arranque del servicio. Cambiarlos requiere reiniciar el servicio. `POST /api/v1/finger/config` solo aplica en tiempo de ejecución los parámetros de conexión con el procesamiento (en los nodos `master`) y los umbrales de las métricas operativas. ## Contadores de uso * `GET /api/v1/finger/metrics` expone, en el bloque `usage`, los contadores de uso de la licencia para las operaciones `extract` y `authenticate` completadas con éxito. * Los mismos valores se publican también con los nombres de campo de la versión 2.1.0: `usageCountersEnabled`, `extractCount`, `authenticateCount` y `totalCount`. * Los contadores solo están disponibles si la licencia los tiene habilitados; en caso contrario, `usage.enabled` vale `false` y los contadores valen `0`. * `usage.total` se calcula como la suma de `extract` y `authenticate`. ## Consideraciones de rendimiento | Dimensión | Guía | | ------------------------ | --------------------------------------------------------------------------------------- | | Rendimiento (throughput) | Escala con la capacidad de procesamiento del clúster y el tamaño del pool de conexiones | | Latencia | Afectada por el timeout de petición de procesamiento y los reintentos | | Concurrencia | Influida por `number_of_threads` y `engine_pool_size` | | Tamaño de payload | Controlado por `client_max_body_size` | ## Notas operativas * Durante el arranque del contenedor, los componentes de procesamiento requieren un tiempo de calentamiento: el servicio no abre el puerto REST hasta pasados al menos 60 segundos en un nodo `master` (30 segundos en un nodo `worker`). * `GET /api/v1/finger/health` valida la licencia y ejecuta en cada llamada una comprobación activa de los componentes de procesamiento. Responde siempre HTTP `200`, con `message` igual a `Healthy` o `Unhealthy`. * `GET /api/v1/finger/metrics` no ejecuta comprobaciones activas: publica el resultado de la última llamada a `/health` y contadores en memoria, así que es apto para scraping frecuente. * En despliegues orientados a clúster, asegura una configuración de topología consistente entre nodos y la conectividad por los puertos `47500`-`47509`. ## Recomendaciones de seguridad * Despliega detrás de un proxy inverso o una API gateway. * Restringe el acceso entrante a redes de confianza, incluidos los puertos de comunicación del clúster. * Utiliza terminación TLS en la gateway o el balanceador de carga. * Protege los archivos de licencia y configuración montados con permisos de mínimo privilegio. * Mantén `auth_jwt_secret` en un almacén de secretos o inyectado como variable de entorno en lugar de incluirlo directamente en las imágenes. * Cuando JWT esté habilitado, utiliza tokens HS256 con un claim `exp` válido y protege todos los endpoints no públicos. * Habilita la verificación SSL para la comunicación con el backend de procesamiento cuando la infraestructura lo permita. Los endpoints que permanecen sin autenticación con JWT habilitado son `GET /api/v1/finger/health`, `GET /api/v1/finger/version`, `GET /api/v1/finger/metrics`, `GET /api/v1/finger/metrics/prometheus` y las peticiones `OPTIONS`. ## Logging y monitorización Utiliza estos endpoints para la monitorización: | Endpoint | Uso | | --------------------------------------- | ------------------------------------------------------------------------------------------------ | | `GET /api/v1/finger/health` | Sonda de disponibilidad (readiness): licencia y componentes de procesamiento | | `GET /api/v1/finger/version` | Versión del servicio y estado de la licencia | | `GET /api/v1/finger/metrics` | Snapshot JSON de tráfico, saturación, latencia, uso, calidad, clasificación del estado y alertas | | `GET /api/v1/finger/metrics/prometheus` | Mismo snapshot en formato de exposición Prometheus | Configura los logs con: * `logger_level` * `logger_path` * `logger_file_prefix` * `logger_rotation` * `logger_max_files` ## Notas de compatibilidad * Los payloads de la API para operaciones de huella dactilar utilizan el contrato público introducido en la versión 2.0.0. * Los nombres de campo internos no se exponen en las respuestas públicas. * Los payloads de los endpoints de gestión están documentados en la referencia OpenAPI.