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/ · Kit de integración: ver sección

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 tamaño mínimo (200×200), brillo y que la imagen contenga exactamente un rostro (validate_enrollment_image).

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 envía a /autenticacion/faceid/verificar/ (sesión + CSRF): el servidor compara contra el registro del usuario en sesión; el navegador nunca recibe el token de la empresa.

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/`	Público	Inicio de sesión (el registro público está deshabilitado: las cuentas las crea un administrador).
`/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/faceid/verificar/` · `/autenticacion/monitor/identificar/`	Sesión + CSRF	Endpoints internos (POST) que usan las pantallas web: resuelven empresa e identidad en el servidor.
`/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: inicio con esta documentación.
`/camtest/`	Público	Diagnóstico de cámara del navegador.
`/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	`cod_number`, `face_photo`; opcionales `username`, `nombre`, `apellido`, `email`, `dni_number`, `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` + header `X-Secret-Key`	Devuelve el registro con el nombre de archivo de la foto. Requiere clave secreta.
`delete/`	DELETE	`id` + header `X-Secret-Key`	Elimina un registro. Respeta el máximo de registros configurado.
`reset/`	POST	JSON `{"usernames": [...]}` + header `X-Secret-Key`	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
}

Los errores de negocio (rostro distinto, sin rostro, sin registro) llegan con HTTP 200 e isSuccess: false; un token inválido responde HTTP 403. Todas las consultas se limitan a la empresa del token.

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"

Ejemplo: Python (backend)

from faceid_client import FaceIDClient, FaceIDError   # incluido en el kit

faceid = FaceIDClient(api_key=os.environ['FACEID_API_KEY'])
try:
    r = faceid.verificar(open('captura.jpg', 'rb'), cod_number='1205')
    print(r['is_same_person'], r['similarity_score'])
except FaceIDError as e:
    print('No verificado:', e.message)

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 administrativa en el header X-Secret-Key. La key es un secreto de servidor: nunca debe enviarse al navegador.

Integración en otros proyectos

Kit descargable con la captura de cámara para el navegador y el cliente Python para el backend. Arquitectura: navegador → tu backend → FaceID; la API key vive sólo en tu backend.

faceid-kit-v2.zip — todo el kit
README.md — guía completa para integrar FaceID en otro proyecto
Python: faceid_client.py, ejemplo_django.py, ejemplo_fastapi.py
Node: faceid-client.mjs, ejemplo-express.mjs
PHP: FaceIDClient.php, ejemplo.php, ejemplo_laravel.php
React: useFaceIDCapture.js, FaceIDVerificar.jsx, README
Navegador: faceid-capture.js (cámara sin dependencias), ejemplo.html, demo de marcación (modo simulado, sin servidor)

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: apps/faceid/templates/documentacion/_contenido.html (se muestra en /documentacion/ y /panel/).