# Trabajadores · Referencia

> Trabajadores y relojes.

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

## Listar trabajadores

`GET /v1/workers` · scope `workers:read` · [ver en la web](https://safeonuba.com/desarrolladores/referencia/trabajadores#listWorkers)

### Parámetros de consulta

- `site_id` (string (uuid))
- `limit` (integer): Elementos por página (máximo 500). (de 1 a 500, por defecto 100)
- `cursor` (string): El `next_cursor` de la página anterior.

### Respuestas

- `200`: Trabajadores. → `WorkerPage` (`application/json`)
- `401`: Falta el token, ha caducado o se ha revocado. → `Problem` (`application/problem+json`)
- `403`: Al token le falta el scope que pide la ruta, o el centro no es del cliente. → `Problem` (`application/problem+json`)
- `429`: Demasiadas peticiones, o demasiado tiempo de consulta: cada cliente tiene un número de peticiones por minuto (600 de serie) y un tiempo de consulta por minuto (30 s de serie), y cada petición gasta lo que tarda, así que una lista larga cuenta más que una alerta suelta. `Retry-After` dice cuándo volver. → `Problem` (`application/problem+json`)

### Ejemplo de petición (sandbox)

```bash
curl "https://sandbox.api.safeonuba.com/v1/workers" \
  -H "Authorization: Bearer $SAFEONUBA_TOKEN"
```

### Respuesta de ejemplo (`200`)

```json
{
  "data": [
    {
      "id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
      "external_id": "EMP-004512",
      "name": "Ana Ejemplo",
      "contractor": "Contrata Ejemplo A",
      "role": "Andamiero",
      "is_active": false,
      "device": {
        "id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
        "serial": "OS-W-0005",
        "battery": 64,
        "date_last_seen": "2026-09-24T11:04:12Z"
      },
      "date_last_seen": "2026-09-24T11:04:12Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0yNFQxMTowNDoxMloifQ"
}
```

## Detalle de un trabajador

`GET /v1/workers/{id}` · scope `workers:read` · [ver en la web](https://safeonuba.com/desarrolladores/referencia/trabajadores#getWorker)

### Parámetros de ruta

- `id` (string (uuid), obligatorio): Id del trabajador.

### Respuestas

- `200`: El trabajador. → `Worker` (`application/json`)
- `401`: Falta el token, ha caducado o se ha revocado. → `Problem` (`application/problem+json`)
- `403`: Al token le falta el scope que pide la ruta, o el centro no es del cliente. → `Problem` (`application/problem+json`)
- `404`: No existe o no lo ve esta identidad. → `Problem` (`application/problem+json`)
- `429`: Demasiadas peticiones, o demasiado tiempo de consulta: cada cliente tiene un número de peticiones por minuto (600 de serie) y un tiempo de consulta por minuto (30 s de serie), y cada petición gasta lo que tarda, así que una lista larga cuenta más que una alerta suelta. `Retry-After` dice cuándo volver. → `Problem` (`application/problem+json`)

### Ejemplo de petición (sandbox)

```bash
curl "https://sandbox.api.safeonuba.com/v1/workers/0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90" \
  -H "Authorization: Bearer $SAFEONUBA_TOKEN"
```

### Respuesta de ejemplo (`200`)

```json
{
  "id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
  "external_id": "EMP-004512",
  "name": "Ana Ejemplo",
  "contractor": "Contrata Ejemplo A",
  "role": "Andamiero",
  "is_active": false,
  "device": {
    "id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
    "serial": "OS-W-0005",
    "battery": 64,
    "date_last_seen": "2026-09-24T11:04:12Z"
  },
  "date_last_seen": "2026-09-24T11:04:12Z"
}
```

## Listar relojes

`GET /v1/devices` · scope `workers:read` · [ver en la web](https://safeonuba.com/desarrolladores/referencia/trabajadores#listDevices)

### Parámetros de consulta

- `site_id` (string (uuid))
- `limit` (integer): Elementos por página (máximo 500). (de 1 a 500, por defecto 100)
- `cursor` (string): El `next_cursor` de la página anterior.

### Respuestas

- `200`: Relojes: batería, si está puesto, última conexión. → `DevicePage` (`application/json`)
- `401`: Falta el token, ha caducado o se ha revocado. → `Problem` (`application/problem+json`)
- `403`: Al token le falta el scope que pide la ruta, o el centro no es del cliente. → `Problem` (`application/problem+json`)
- `429`: Demasiadas peticiones, o demasiado tiempo de consulta: cada cliente tiene un número de peticiones por minuto (600 de serie) y un tiempo de consulta por minuto (30 s de serie), y cada petición gasta lo que tarda, así que una lista larga cuenta más que una alerta suelta. `Retry-After` dice cuándo volver. → `Problem` (`application/problem+json`)

### Ejemplo de petición (sandbox)

```bash
curl "https://sandbox.api.safeonuba.com/v1/devices" \
  -H "Authorization: Bearer $SAFEONUBA_TOKEN"
```

### Respuesta de ejemplo (`200`)

```json
{
  "data": [
    {
      "id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
      "serial": "OS-W-0005",
      "battery": 64,
      "date_last_seen": "2026-09-24T11:04:12Z",
      "model": "Galaxy Watch6",
      "status": "active",
      "worn": true,
      "worker": {
        "id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
        "external_id": "EMP-004512",
        "name": "Ana Ejemplo",
        "contractor": "Contrata Ejemplo A"
      }
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0yNFQxMTowNDoxMloifQ"
}
```