API de dispositivos biométricos

ATV Asistencias expone una API para que un conector de marcaje envíe marcas y sincronice la nómina. Cada dispositivo se autentica con un token propio, generado al registrarlo en la plataforma.

Biopad: la terminal requiere un adaptador compatible con su protocolo/AXS Biopad. Consulte la guía de integración Biopad; no configure esta API directamente en la terminal sin validar que el firmware soporte JSON y encabezados HTTP.

Modalidades de marcaje soportadas: rostro, huella, tarjeta de aproximación y clave. Al menos dos medios de identificación deben estar disponibles para cada trabajador (Dictamen 2.1.6 / 3.6).

Autenticación

Todas las llamadas incluyen el token del dispositivo en la cabecera:

X-Device-Token: DEV-xxxxxxxxxxxxxxxxxxxx

Endpoints

POST /api/dispositivo/marcas

Envía una o varias marcas. Las marcas capturadas sin conexión se aceptan con su marca de tiempo original (Dictamen 2.3.1). El sistema genera el hash SHA-256, el comprobante y el correo.

POST /api/dispositivo/marcas
X-Device-Token: DEV-...
Content-Type: application/json

{
  "marcas": [
    { "pin": "1001", "tipo": "entrada", "ts": "2026-07-12 08:59:55", "tipo_lectura": "huella" },
    { "pin": "1002", "tipo": "salida",  "ts": "2026-07-12 18:03:10", "tipo_lectura": "rostro" }
  ]
}

Campos:

Campo	Descripción
`pin`	PIN de reloj del trabajador (campo PIN reloj de su ficha).
`tipo`	`entrada`, `salida`, `colacion_inicio` o `colacion_fin`.
`ts`	Fecha y hora de la marca (`YYYY-MM-DD HH:MM:SS`). Si se omite, se usa la hora del servidor.
`tipo_lectura`	Opcional: `huella`, `rostro`, `tarjeta`, `clave`.

Respuesta: un resultado por marca, con el hash generado o el código del intento fallido si el PIN no corresponde a un trabajador activo (2.10).

{ "resultados": [
  { "pin": "1001", "ok": true, "hash": "a7f3..." },
  { "pin": "9999", "ok": false, "codigo": "F-2B4A9C1D" }
]}

GET /api/dispositivo/empleados

Devuelve la nómina activa de la empresa del dispositivo, para enrolar credenciales en el equipo.

GET /api/dispositivo/empleados
X-Device-Token: DEV-...
→ { "empleados": [ { "id":1, "rut":"16.234.567-8", "nombres":"Valentina", "apellidos":"Rojas", "pin_reloj":"1001", "tarjeta_numero":null } ], "dispositivo":"Biopad Entrada" }

POST /api/dispositivo/heartbeat

Señal de vida periódica del equipo. Permite monitorear disponibilidad y sincronizar la hora del servidor.

POST /api/dispositivo/heartbeat
X-Device-Token: DEV-...
{ "ip": "192.168.1.50", "fw_version": "1.4.2" }
→ { "ok": true, "hora_servidor": "2026-07-12 09:00:01" }

Registro de un dispositivo

Ingrese a la plataforma como administrador → Dispositivos → Registrar dispositivo.
Indique nombre, marca, modelo, sucursal, número de reloj y tipos de lectura.
Copie el token generado y configúrelo en el equipo.

Integración con control de acceso (Dictamen 2.12): un sistema de control de acceso (torniquetes, puertas) puede integrarse con el registro de asistencia una vez que el sistema esté autorizado por la DT, sin alterar las condiciones bajo las que fue certificado, y respaldando la integración con un informe fechado y firmado.

ATV Asistencia v1.0.0 — ATV Electronic