> 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 con los servicios de procesamiento de huella dactilar requeridos |

## Restricciones de runtime y compilación

* Arquitectura compatible: x86\_64
* Sistema operativo objetivo compatible: Linux
* Runtime base del contenedor: Ubuntu 20.04

## 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
* Adecuado para escalado horizontal detrás de un balanceador de carga

## Disponibilidad de endpoints por rol

| Rol      | Endpoints                                                           |
| -------- | ------------------------------------------------------------------- |
| `master` | `extract`, `authenticate`, `health`, `version`, `metrics`, `config` |
| `worker` | `health`, `version`, `metrics`, `config`                            |

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

## Modelo de configuración

### Orden de precedencia

De mayor a menor prioridad:

1. Variables de entorno
2. `config.json`
3. Valores por defecto del servicio

### Grupos de configuración en tiempo de ejecución

* Ajustes del gestor REST: puerto de escucha, hilos, timeout, tamaño de body, logging
* 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 de descubrimiento del nodo master
* Contadores de uso de licencia: habilitados mediante la clave de metadatos de licencia `ActivateUsageCounters`

Los ajustes de autenticación JWT se aplican durante el arranque del servicio. Cambiarlos requiere reiniciar el servicio.

## Contadores de uso

* `GET /api/v1/finger/metrics` expone los contadores de uso de las operaciones `extract` y `authenticate` completadas con éxito.
* Los campos de la respuesta son: `usageCountersEnabled`, `extractCount`, `authenticateCount`, `totalCount`.
* Los atributos de medición de licencia utilizados por el servicio son `FingerExtractCounter` y `FingerAuthenticateCounter`.
* `totalCount` se calcula como `extractCount + authenticateCount`.

## Consideraciones de rendimiento

| Dimensión                | Guía                                                                  |
| ------------------------ | --------------------------------------------------------------------- |
| Rendimiento (throughput) | Escala con la capacidad del engine y el tamaño del pool de conexiones |
| Latencia                 | Afectada por el timeout de petición del engine 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 servicios de procesamiento pueden requerir un tiempo de calentamiento.
* Las comprobaciones de salud validan el contexto del servicio, la licencia y la disponibilidad del procesamiento.
* En despliegues orientados a clúster, asegura una configuración de descubrimiento consistente entre nodos.

## Recomendaciones de seguridad

* Despliega detrás de un proxy inverso o una API gateway.
* Restringe el acceso entrante a redes de confianza.
* 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 públicos que permanecen sin autenticación son `GET /api/v1/finger/health`, `GET /api/v1/finger/version` y las peticiones de preflight `OPTIONS`.

## Logging y monitorización

Utiliza estos endpoints para comprobaciones de disponibilidad (liveness):

* `GET /api/v1/finger/health`
* `GET /api/v1/finger/version`
* `GET /api/v1/finger/metrics`

Configura los logs con:

* `logger_level`
* `logger_path`
* `logger_rotation`
* `logger_max_files`

## Notas de compatibilidad

* Los payloads de la API para operaciones de huella dactilar utilizan el contrato público 2.0.0.
* Los nombres de campo internos no se exponen en las respuestas públicas.
* Los payloads de los endpoints de gestión son estables y están documentados en OpenAPI.