# Evacuaciones · Referencia

> Estado, recuento por estado y por punto, descartes y quién falta.

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

## Listar evacuaciones

`GET /v1/musters` · scope `musters:read` · [ver en la web](https://safeonuba.com/desarrolladores/referencia/evacuaciones#listMusters)

### Parámetros de consulta

- `site_id` (string (uuid))
- `status` (string) Valores: `active`, `completed`, `cancelled`.
- `since` (string (date-time))
- `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`: Evacuaciones activas e históricas. → `MusterPage` (`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/musters" \
  -H "Authorization: Bearer $SAFEONUBA_TOKEN"
```

### Respuesta de ejemplo (`200`)

```json
{
  "data": [
    {
      "id": "4fb94227-7afb-442d-a672-6fd82069518f",
      "site": {
        "id": "11111111-1111-1111-1111-111111111111",
        "name": "Planta Ejemplo — simulación"
      },
      "status": "active",
      "phase": "evacuating",
      "kind": "general",
      "reason": "Fuga en Mantenimiento",
      "started_at": "2026-09-24T18:31:06Z",
      "ended_at": null,
      "deadline": null,
      "origin": {
        "latitude": 39.97894,
        "longitude": -2.96877,
        "radius_m": 400,
        "label": "Mantenimiento — permiso PT-0453",
        "zone": {
          "id": "22222222-2222-2222-2222-222222222203",
          "name": "Mantenimiento — permiso PT-0453"
        }
      },
      "targets_revision": 3,
      "totals": {
        "expected": 9,
        "safe": 6,
        "help": 0,
        "wrong_point": 0,
        "pending": 2,
        "no_signal": 0,
        "not_worn": 1
      },
      "assembly_points": [
        {
          "id": "22222222-2222-2222-2222-222222222204",
          "name": "Punto de reunión PR-1",
          "status": "excluded",
          "count": 0,
          "excluded": {
            "reason": "A 371 m del origen (radio 400 m)",
            "recommended": true,
            "at": "2026-09-24T18:31:06Z",
            "by": "Elena Ejemplo"
          }
        },
        {
          "id": "22222222-2222-2222-2222-222222222205",
          "name": "Punto de reunión PR-2",
          "status": "excluded",
          "count": 0,
          "excluded": {
            "reason": "A sotavento: viento del SO a 9 km/h",
            "recommended": true,
            "at": "2026-09-24T18:31:42Z",
            "by": "Elena Ejemplo"
          }
        },
        {
          "id": "f6040b41-be81-4bf3-af68-bfaf3e284c54",
          "name": "Punto de reunión PR-3 · Zona alta",
          "status": "available",
          "count": 6,
          "excluded": null
        }
      ]
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0yNFQxMTowNDoxMloifQ"
}
```

## Estado y recuento de una evacuación

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

El recuento lo cuenta el servidor con la misma regla que el panel y el cierre: posición precisa dentro de un punto válido, o llegada declarada a uno.

### Parámetros de ruta

- `id` (string (uuid), obligatorio): Id de la evacuación.

### Respuestas

- `200`: La evacuación. → `Muster` (`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 es de un centro 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/musters/0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90" \
  -H "Authorization: Bearer $SAFEONUBA_TOKEN"
```

### Respuesta de ejemplo (`200`)

```json
{
  "id": "4fb94227-7afb-442d-a672-6fd82069518f",
  "site": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Planta Ejemplo — simulación"
  },
  "status": "active",
  "phase": "evacuating",
  "kind": "general",
  "reason": "Fuga en Mantenimiento",
  "started_at": "2026-09-24T18:31:06Z",
  "ended_at": null,
  "deadline": null,
  "origin": {
    "latitude": 39.97894,
    "longitude": -2.96877,
    "radius_m": 400,
    "label": "Mantenimiento — permiso PT-0453",
    "zone": {
      "id": "22222222-2222-2222-2222-222222222203",
      "name": "Mantenimiento — permiso PT-0453"
    }
  },
  "targets_revision": 3,
  "totals": {
    "expected": 9,
    "safe": 6,
    "help": 0,
    "wrong_point": 0,
    "pending": 2,
    "no_signal": 0,
    "not_worn": 1
  },
  "assembly_points": [
    {
      "id": "22222222-2222-2222-2222-222222222204",
      "name": "Punto de reunión PR-1",
      "status": "excluded",
      "count": 0,
      "excluded": {
        "reason": "A 371 m del origen (radio 400 m)",
        "recommended": true,
        "at": "2026-09-24T18:31:06Z",
        "by": "Elena Ejemplo"
      }
    },
    {
      "id": "22222222-2222-2222-2222-222222222205",
      "name": "Punto de reunión PR-2",
      "status": "excluded",
      "count": 0,
      "excluded": {
        "reason": "A sotavento: viento del SO a 9 km/h",
        "recommended": true,
        "at": "2026-09-24T18:31:42Z",
        "by": "Elena Ejemplo"
      }
    },
    {
      "id": "f6040b41-be81-4bf3-af68-bfaf3e284c54",
      "name": "Punto de reunión PR-3 · Zona alta",
      "status": "available",
      "count": 6,
      "excluded": null
    }
  ]
}
```

## Quién falta

`GET /v1/musters/{id}/missing` · scope `musters:read` · [ver en la web](https://safeonuba.com/desarrolladores/referencia/evacuaciones#listMissingWorkers)

Primero quien pide ayuda o necesita rescate, después quien está en un punto que no sirve, sin señal, sin el reloj puesto y saliendo. La última posición solo con el scope `positions:read`, y si el velo la deja ver.

### Parámetros de ruta

- `id` (string (uuid), obligatorio): Id de la evacuación.

### Respuestas

- `200`: Quién falta, por urgencia. → `MissingWorkerList` (`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 es de un centro 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/musters/0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90/missing" \
  -H "Authorization: Bearer $SAFEONUBA_TOKEN"
```

### Respuesta de ejemplo (`200`)

```json
{
  "data": [
    {
      "worker": {
        "id": "33333333-3333-3333-3333-333333333305",
        "external_id": "EMP-004512",
        "contractor": "Contrata Ejemplo A"
      },
      "device": {
        "id": "44444444-4444-4444-4444-444444444405",
        "serial": "OS-W-0005",
        "battery": 61,
        "date_last_seen": "2026-09-24T18:33:40Z"
      },
      "status": "wrong_point",
      "needs_rescue": false,
      "help_reason": null,
      "assembly_point": {
        "id": "22222222-2222-2222-2222-222222222205",
        "name": "Punto de reunión PR-2",
        "valid": false
      },
      "declared_at": "2026-09-24T18:32:10Z",
      "last_seen_at": "2026-09-24T18:33:40Z",
      "location": null,
      "location_withheld": false
    }
  ]
}
```