# Sandbox · Referencia

> Escenarios de prueba con relojes simulados, para integrar sin relojes. Solo en `sandbox.api.safeonuba.com`.

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

## Lanzar un escenario de prueba

`POST /v1/sandbox/scenarios` · cualquier token · [ver en la web](https://safeonuba.com/desarrolladores/referencia/sandbox#runSandboxScenario)

**Solo en `sandbox.api.safeonuba.com`**; en producción, 404. Un escenario no inventa alertas: relojes simulados de un centro de sandbox mandan sus hechos y el motor de siempre decide, así que lo que llega —webhook, `GET`, recuento— es lo mismo que llegaría de un reloj de verdad, marcado `simulated: true`. Como mucho cinco abiertos a la vez por cliente y una evacuación por centro.

### Cuerpo (`application/json`, esquema `SandboxScenarioRequest`)

- `scenario` (SandboxScenario, obligatorio) Valores: `sos`, `fall`, `heat_stress`, `evacuation`.
- `site_id` (string (uuid)): El centro de sandbox. Sin él, el primero de los vuestros que sea de sandbox.

### Respuestas

- `202`: Lanzado. → `SandboxScenarioRun` (`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 es el sandbox, o el centro no es vuestro. → `Problem` (`application/problem+json`)
- `409`: Ya hay una evacuación en marcha en ese centro, o cinco escenarios abiertos. → `Problem` (`application/problem+json`)
- `422`: El centro no es de sandbox, o tiene un reloj de verdad y no corre nada. → `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 -X POST "https://sandbox.api.safeonuba.com/v1/sandbox/scenarios" \
  -H "Authorization: Bearer $SAFEONUBA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "scenario": "sos"
}'
```

### Respuesta de ejemplo (`202`)

```json
{
  "run_id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
  "scenario": "sos",
  "site_id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
  "resource": {
    "type": "alert",
    "id": "0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90"
  },
  "ends_at": "2026-09-24T11:04:12Z"
}
```