> 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/api_reference.md).

# Guía de referencia de la API

## 1. Introducción

Este documento incluye la descripción de la API REST del servicio **Facephi Finger Service** versión 2.2.1. Todas las rutas cuelgan de `/api/v1/finger` y el servicio escucha en el puerto `6982`.

## 2. API REST

El servicio ofrece dos endpoints principales, que reciben y devuelven JSON y solo están disponibles en los nodos con rol `master`:

* **`POST /api/v1/finger/extract`**: extrae una plantilla de huella dactilar a partir de una imagen codificada en Base64 (`wsq`, `bmp`, `png`, `jpg` o `jp2`) y devuelve la plantilla junto con su calidad.
* **`POST /api/v1/finger/authenticate`**: autentica 1:1 dos huellas dactilares, enviadas como imágenes, como plantillas o como una combinación de ambas, y devuelve el resultado (`authStatus`) y la similitud entre ellas (`similarity`).

Endpoints de gestión, disponibles en todos los nodos:

* **`GET /api/v1/finger/version`**: versión del servicio y estado de la licencia.
* **`GET /api/v1/finger/health`**: comprobación activa de la licencia y de los componentes de procesamiento. Responde siempre con HTTP 200; el estado está en `message`.
* **`GET /api/v1/finger/metrics`**: snapshot JSON de métricas operativas, de uso y de calidad.
* **`GET /api/v1/finger/metrics/prometheus`**: el mismo snapshot en formato de exposición Prometheus.
* **`GET|POST /api/v1/finger/config`**: obtiene la configuración o actualiza en tiempo de ejecución los parámetros de conexión con el procesamiento y los umbrales de las métricas operativas. Los ajustes de arranque de la autenticación JWT se ocultan en la respuesta GET y se rechazan en la operación POST.

La autenticación JWT opcional puede habilitarse en el arranque desde `config.json` o mediante las variables de entorno `FACEPHI_FINGER_REST_AUTH_*`. Cuando el JWT está habilitado, `GET /api/v1/finger/version`, `GET /api/v1/finger/health`, `GET /api/v1/finger/metrics`, `GET /api/v1/finger/metrics/prometheus` y las peticiones `OPTIONS` siguen siendo públicos, mientras que el resto de endpoints requieren un JWT válido mediante `Authorization: Bearer <jwt>` o la cabecera de API key configurada.

La descripción funcional completa (contrato de las operaciones, errores y métricas) está en la [página del servicio](https://docs.facephi.com/sdks/backend-sdk/finger.md).
