Documentación técnica

Documentación técnica de FaceID

FaceID es una plataforma de verificación de identidad facial construida sobre Django + DeepFace (modelo ArcFace). Ofrece interfaces web para enrolamiento, verificación y marcación de asistencia, y un API REST multiempresa para integrarla en sistemas externos.

URL base del API: https://faceapi.epunemi.gob.ec/api/faceid/v1.0.0/ · Documentación interactiva: /api/swagger/ · Guía con ejemplos (requiere sesión): /panel/

Procesos del sistema

1. Enrolamiento (registro del rostro)

1

El usuario captura su foto desde el navegador (/autenticacion/register/) o un sistema externo la envía vía POST save/.

2

El servidor valida que la imagen contenga exactamente un rostro nítido (validate_deepface).

3

Se guarda la foto en BiometricData y se precalcula el embedding facial (vector ArcFace) para identificación 1:N.

2. Verificación 1:1 (¿es esta persona X?)

1

El cliente envía una captura en vivo + identificador del usuario (cod_number, username o email) a POST verify_face/.

2

Se compara contra la foto registrada con ArcFace; opcionalmente se ejecuta anti-spoofing (FasNet) sobre la captura.

3

Respuesta: is_same_person, similarity_score, distance, threshold y datos del registro.

3. Marcación de asistencia

1

En /autenticacion/registrar_marcada/ el usuario elige jornada (entrada/salida/almuerzo).

2

Prueba de vida en el navegador (MediaPipe FaceMesh): parpadeo, sonrisa o inclinación aleatoria, con 3 intentos.

3

La captura se verifica vía verify_face/; si coincide, la marcada queda registrada con fecha y hora.

4. Identificación 1:N (¿quién es esta persona?)

1

Una captura se envía a POST identify/ sin indicar identidad.

2

Se calcula su embedding y se compara por distancia coseno contra los embeddings precalculados de todos los usuarios activos de la empresa.

3

Si la mejor distancia supera el umbral, found=false — es la base del Monitor FaceID (/autenticacion/monitor/) que alerta ante personas no registradas.

Interfaces web

URL	Acceso	Qué hace
`/`	Público	Landing del producto.
`/login/` · `/register/`	Público	Inicio de sesión y creación de cuenta.
`/documentacion/`	Público	Esta documentación técnica.
`/consultas/`	Interno	Endpoint AJAX de consultas (búsqueda de personas); sin acción redirige aquí.
`/autenticacion/register/`	Sesión	Enrolamiento: captura y guarda la foto de referencia del usuario en sesión (reemplaza la anterior).
`/autenticacion/faceid/`	Sesión	Verificación de identidad con prueba de vida contra el registro del usuario.
`/autenticacion/registrar_marcada/`	Sesión	Marcación de asistencia por rostro (jornadas, prueba de vida, 3 intentos, registro del día).
`/autenticacion/monitor/`	Sesión	Monitor continuo 1:N: identifica a cada persona en cámara y alerta si no está registrada.
`/autenticacion/usuarios_face_id/`	Sesión + permiso	CRUD de registros biométricos, con prueba de verificación por cámara por registro.
`/seguridad/empresas/`	Sesión + permiso	Empresas y sus tokens de API; consumo (último uso, 30 días, total) y ranking de uso.
`/panel/`	Sesión + permiso	Panel administrativo con la guía del API.
`/admin/`	Superusuario	Django admin (incluye bitácora de consumo del API).

API REST — `/api/faceid/v1.0.0/biometric/`

Endpoint	Método	Parámetros clave	Qué hace
`verify_face/`	POST	`face_photo_file` + `cod_number` \| `username` \| `email`	Verificación 1:1 contra el registro del usuario. Devuelve similitud y umbral.
`identify/`	POST	`face_photo_file`	Identificación 1:N: a quién pertenece el rostro. `found=false` si es desconocido.
`verify_face_public/`	POST	`face_photo_url`, `url_comparar`	Compara dos imágenes por URL (validación anti-SSRF: solo http/https públicos).
`save/`	POST	`token_empresa`, `cod_number`, `face_photo`, `permite_actualizar`	Enrola o actualiza un registro biométrico y precalcula su embedding.
`load/`	GET	`id`	Devuelve un registro biométrico por ID.
`load_faces/`	GET	`username` \| `email`	Lista los registros de un usuario y el período biométrico vigente.
`biometric_data/`	GET	`username` \| `email`, `secretKey`	Devuelve el registro con el nombre de archivo de la foto. Requiere clave secreta.
`delete/`	DELETE	`id`, `secretKey`	Elimina un registro. Respeta el máximo de registros configurado.
`reset/`	POST	`secretKey`, `usernames[]`	Desactiva los registros de una lista de usuarios para que vuelvan a enrolarse.

Formato de respuesta

Todas las respuestas siguen la misma envoltura:

{
  "isSuccess": true,
  "message": "Acción realizada correctamente.",
  "aData": { ... }        // datos del recurso o resultado
}

Ejemplo: verificación 1:1

curl -X POST "https://faceapi.epunemi.gob.ec/api/faceid/v1.0.0/biometric/verify_face/" \
  -H "Authorization: Bearer TOKEN_DE_TU_EMPRESA" \
  -F "cod_number=1205" \
  -F "face_photo_file=@captura.jpg"

Autenticación

Todo el API exige el header Authorization: Bearer <token_empresa>. El token identifica a la empresa: sus registros biométricos están aislados del resto y cada request queda asociado a ella en la bitácora de consumo. Los tokens se generan y administran en /seguridad/empresas/. Las operaciones destructivas (delete, reset) exigen además la clave secretKey.

Trazabilidad y logs

Consumo del API: cada request autenticado crea un registro en ApiUsageLog (empresa, endpoint, método, IP, user-agent, código de respuesta, duración). Visible en el Django admin y resumido por empresa en /seguridad/empresas/.
Auditoría administrativa: altas, cambios y eliminaciones en los módulos web quedan en la bitácora de auditoría con usuario e IP.
Verificaciones: cada verificación exitosa actualiza is_verify y date_verify del registro biométrico.

Configuración (variables de entorno)

Variable	Default	Efecto
`ANTI_SPOOFING`	`False`	Liveness pasivo (FasNet) sobre la captura en las verificaciones. Bloquea fotos impresas o de pantalla.
`IDENTIFY_DISTANCE_THRESHOLD`	`0.68`	Distancia coseno máxima para aceptar un match en la identificación 1:N.
`ALLOWED_IMAGE_URL_HOSTS`	vacío	Allowlist de hosts para `verify_face_public` (separados por coma).
`KEY_LOAD_SECRET_KEY`	vacío	Clave para operaciones sensibles (`biometric_data`, `delete`, `reset`).
`MAX_REGISTERED_FACES`	`1`	Máximo de registros biométricos por usuario.
`USE_DEEP_FACE`	`False`	Selector de motor de comparación (DeepFace vs Face++).

Motor de comparación: DeepFace ArcFace con detector retinaface, umbral de similitud 0.5. Fuente de esta documentación en el repositorio: docs/ENDPOINTS.md.