# Evacuaciones y recuento

> Tipos, estados y fases de una evacuación, el recuento por persona y por punto de reunión, los puntos descartados y la lista de quién falta.

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

Una **evacuación** (`muster` en la API) es el recuento de una planta cuando hay que salir: quién ha llegado a un punto de reunión válido, quién pide ayuda y quién falta. Es lo que más importa que llegue bien a tu sala, y por eso sus eventos salen por delante de casi todo lo demás.

> **La API no abre evacuaciones**
>
> En v1 una evacuación empieza siempre en el panel de SafeOnuba: el sistema puede proponerla, pero la decide una persona. Tu sala la recibe en cuanto empieza (`muster.started`) y la sigue hasta que termina.

## Tipo, estado y fase

| kind | Qué significa |
| --- | --- |
| `general` | Evacuación general. |
| `tsunami` | Por tsunami. Puede traer `deadline`, la hora límite. |
| `earthquake` | Por terremoto. |

El tipo puede cambiar durante la evacuación (`muster.kind_changed`), y con él los puntos de reunión que valen.

| status | Qué significa |
| --- | --- |
| `active` | En marcha. |
| `completed` | Terminada. |
| `cancelled` | Cancelada. |

| phase | Qué significa |
| --- | --- |
| `evacuating` | Se está evacuando. |
| `inspecting` | El recuento está completo y la sala revisa la planta. Los relojes dicen «no vuelvas hasta nuevo aviso». |

Otros campos útiles:

- `reason`: el motivo, en texto.
- `origin`: de dónde viene la emergencia (coordenadas, radio y zona). `null` en una evacuación sin origen, como un simulacro general.
- `deadline`: en un tsunami, la hora límite y de dónde sale: `official` (un aviso oficial) o `plan_estimate` (el techo del plan de la zona). Nunca es un cálculo físico.

## El recuento

`GET /v1/musters/{id}` devuelve la evacuación con su recuento en `totals`, calculado en 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.

Cada persona está en uno de estos estados:

| Estado | Qué quiere decir |
| --- | --- |
| `safe` | A salvo en un punto de reunión válido. |
| `help` | Pide ayuda: atrapada (`trapped`), herida (`injured`) o ayudando a otra persona (`helping`). |
| `wrong_point` | En un punto de reunión que no vale para este tipo de evacuación, o que la sala ha descartado. |
| `pending` | Todavía no ha llegado. |
| `no_signal` | Su reloj no comunica. |
| `not_worn` | No lleva el reloj puesto. |

`totals` trae `expected` (cuántas personas se esperan) y el número de personas en cada estado.

> **Una evacuación cerrada guarda menos**
>
> Al cerrar solo se registran los llegados y el total. En una evacuación terminada, el resto de cifras de `totals` y el `count` de cada punto salen `null`.

## Puntos de reunión

`assembly_points` lista los destinos del tipo de evacuación, descartados incluidos, con cuántas personas hay a salvo en cada uno (`count`).

La sala puede **descartar** un punto durante la evacuación, por ejemplo porque queda dentro del radio de la emergencia o a sotavento, y también rehabilitarlo. Un punto descartado tiene `status: "excluded"` y un objeto `excluded` con:

- `reason`: por qué;
- `recommended`: si lo había recomendado el sistema (por radio o por viento). Quien descarta es siempre una persona;
- `at` y `by`: cuándo y quién.

Cada cambio de destinos sube `targets_revision` y emite `muster.targets_changed`. Quien estaba en un punto descartado pasa a `wrong_point`.

## Quién falta

`GET /v1/musters/{id}/missing` devuelve las personas que no están a salvo, ordenadas por urgencia: 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.

- `needs_rescue`: tiene un SOS o una caída abierta y no ha llegado. No puede salir por su pie.
- `help_reason`: `trapped`, `injured` o `helping`.
- `assembly_point`: el punto donde está o dijo estar, con `valid: false` si no sirve.
- `location`: la última posición, solo con el scope `positions:read` y si la privacidad de la planta la deja ver. Si no, `location_withheld: true`.

## Eventos de una evacuación

| Evento | Cuándo |
| --- | --- |
| `muster.started` | Empieza la evacuación. |
| `muster.kind_changed` | Cambia el tipo. |
| `muster.phase_changed` | Cambia la fase (`evacuating`, `inspecting`). |
| `muster.targets_changed` | La sala ha descartado o rehabilitado un punto de reunión. |
| `muster.updated` | El recuento ha cambiado. Se comprueba cada 5 segundos y solo se emite si cambia. |
| `muster.worker_missing` | Falta una persona. |
| `muster.ended` | Termina. |

Una persona que pide ayuda durante la evacuación genera además una alerta `evacuation_help` (`alert.created`), que lleva el `muster_id` en sus detalles.

Cada evento trae la evacuación completa en `data.muster`, así que tu sala puede repintar el banner con el último que le llegue. Como el orden de entrega no está garantizado, quédate con el más reciente por `created_at` (ver [Webhooks](https://safeonuba.com/desarrolladores/webhooks#orden)).

## Probarlo sin evacuar a nadie

El sandbox tiene un escenario que recorre una evacuación entera en 3 minutos: llegadas, un punto descartado, una petición de ayuda y el cierre. Ver [Sandbox](https://safeonuba.com/desarrolladores/sandbox#evacuacion-completa).