Conceptos
Trabajadores y relojes
Cómo identifica la API a cada persona y a su reloj: identificador de empresa, nombre opcional por contrato, batería, si lo lleva puesto y última conexión.
Cada persona lleva un reloj. La API los expone por separado —trabajadores y relojes— y los relaciona entre sí. Los dos piden el scope workers:read.
Trabajadores
GET /v1/workers y GET /v1/workers/{id}.
| Campo | Qué es |
|---|---|
id | UUID del trabajador en SafeOnuba. |
external_id | Su código en tu empresa, el de tu sistema de personal. null si no se ha dado. |
name | Nombre y apellidos. Solo si el contrato lo incluye; si no, la propiedad no aparece. |
contractor | La contrata para la que trabaja, o null. |
role | Su puesto, o null. |
is_active | Si está dado de alta. |
device | El reloj que tiene asignado. |
date_last_seen | Lo más reciente entre su última posición y el último contacto del reloj. |
Sin nombres
Los nombres de los trabajadores son opcionales por contrato. Sin ellos, la API identifica a cada persona por su external_id, el mismo código que ya usa tu empresa. Para cruzar con tu sistema de personal o de control de accesos, usa ese campo, que no depende de que el contrato incluya nombres.
El mismo criterio se aplica en todas partes: en worker dentro de una alerta, en la lista de quién falta y en las posiciones.
Lo que ve tu cliente
La API ve lo mismo que una persona del panel con esos permisos, incluido el alcance por contrata. Un trabajador que tu identidad no ve responde 404, como si no existiera.
Relojes
GET /v1/devices devuelve los relojes con su estado.
| Campo | Qué es |
|---|---|
id, serial | Identificador y número de serie. |
model | Modelo, o null. |
status | Estado del reloj en el inventario. |
battery | Batería en porcentaje, o null. |
worn | Si lo lleva puesto. null si no se sabe, porque el reloj no tiene sensor de muñeca. |
date_last_seen | Último contacto. |
worker | A quién está asignado. |
| status | Qué significa |
|---|---|
active | En uso. |
inactive | Fuera de uso. |
maintenance | En mantenimiento. |
lost | Perdido. |
Un reloj que deja de comunicar o se queda sin batería genera una alerta (device_offline, low_battery). No hace falta consultar esta lista en bucle para enterarse: llegan por webhook como cualquier otra alerta.
Nunca hay constantes vitales
Ni el trabajador ni el reloj traen pulso, temperatura ni ninguna otra constante, sueltas ni agregadas. Ver Privacidad y seguridad.