Dispositivos edge

Esta guía es para integradores que conectan un dispositivo de asistencia (servidor edge o kiosko) con Inspow. El dispositivo procesa el biométrico localmente y solo intercambia con la nube eventos, estados y señales de salud. Los endpoints concretos están en la Referencia API (busca las etiquetas Attendance - Devices, Attendance - Edge Sync y Attendance - Biometric Consent en el sidebar).

El scope DEVICE

Un dispositivo se autentica con una API Key de scope device. Es deny-by-default: solo puede llamar a los endpoints que lo declaran explícitamente (registrar eventos de asistencia, sincronizar roster, reportar estado de enrolamiento y enviar heartbeats). Una key device filtrada no puede tocar el resto del API. Ver API Keys para el modelo general de claves.

Vinculación (pairing por código)

El dispositivo no se configura con secretos a mano; se vincula como un Chromecast:

1. En el panel se crea el dispositivo y se genera un código de un solo uso (TTL corto).
2. El dispositivo canjea el código en el endpoint público de intercambio (pairing/exchange) y recibe su API Key device (en claro, una sola vez).
3. El código es de un solo uso, con caducidad y limitado por IP; el mismo error se devuelve para todos los modos de fallo (sin oráculo de enumeración).

Re-vincular un dispositivo revoca su key anterior. Revocar el dispositivo desde el panel mata la key al instante (kill-switch).

Protocolo de sincronización (/edge/*)

Con su key device, el dispositivo usa tres operaciones, además del registro de asistencia:

Operación	Sentido	Para qué
roster (delta por cursor)	nube → edge	La lista de personas habilitadas para enrolar: id, nombre, grado, estado de consentimiento. Sin fotos ni datos de contacto.
enrollment-status	edge → nube	El dispositivo reporta enrolled / re_enroll_due / deleted con una clave opaca. Reportar un enrolamiento sin consentimiento vigente se rechaza con 403 y queda en auditoría.
heartbeat	edge → nube	Señales operativas (versión, cola pendiente, eventos del día, latencia, tasa de incertidumbre). Nunca biométrico.

Los eventos de asistencia no usan un endpoint nuevo: el dispositivo postea al endpoint unificado de registro (POST /restaurant/attendance-record/register) con su key device, con un requestId idempotente para reintentos seguros sin duplicar.

La frontera que el biométrico nunca cruza

Viaja a Inspow	Jamás sale del colegio
Eventos de asistencia (id de persona, método, puntaje, dispositivo, marca de tiempo)	Imágenes / frames
Estado de enrolamiento + clave opaca	Plantillas faciales (los vectores)
Heartbeats (métricas operativas)	Galería, índices, cualquier dato reconstruible
Roster hacia abajo: id + nombre + grado + consentimiento	Datos de contacto, fotos

Nota

Los DTO de heartbeat y de estado son listas blancas cerradas: el dispositivo no puede enviar un embedding ni una imagen aunque quisiera. Ver Privacidad y cumplimiento.