# 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.

Página: https://safeonuba.com/desarrolladores/conceptos/trabajadores-y-relojes · API de SafeOnuba v1 (`api_version: "2026-09-24"`), en vista previa: el contrato puede cambiar.

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](https://safeonuba.com/desarrolladores/privacidad-y-seguridad).