Alertas

Una alerta es algo que ha pasado en la planta y que alguien tiene que atender: un SOS, una caída, una entrada donde no se debe, un reloj sin batería o un aviso de terremoto. Es el objeto central de la API.

El objeto#

La alerta llega completa en cada webhook (data.alert) y es lo que devuelve GET /v1/alerts/{id}. Los campos que más se usan:

La lista entera, campo a campo, está en el esquema Alert.

Tipos#

Un vehículo cerca no es una alerta#

Los avisos de vehículo cerca no generan alertas propias. Van dentro de la alerta de un incidente, en dos listas:

• nearby: quién había a menos de 100 metros cuando saltó una alerta crítica (SOS o caída), personas o vehículos. Da la distancia, nunca la posición, y no cuenta a quien estaba en una zona de privacidad.
• vehicle_warnings: los avisos de vehículo cerca que recibió esa persona en la ventana del incidente, con la distancia y si los vio en el reloj.

Detalles de cada tipo#

details cambia según type. Por ejemplo, SosDetails dice cómo se pidió el SOS (trigger), ZoneDetails trae el permiso de trabajo que regía (permit_reference) y HazardDetails la magnitud, la distancia y si el aviso es oficial. Las variantes están en AlertDetails.

Gravedad#

El filtro severity de GET /v1/alerts y el min_severity de los webhooks son mínimos: high devuelve high y critical.

Estados#

• Reconocer asigna la alerta a quien la reconoce si nadie la llevaba. Reconocer no es cerrar: una alerta reconocida sigue marcando a la persona en el mapa hasta que se cierra.
• Cerrar deja constancia de quién, cuándo y con qué nota, en resolved.
• Una alerta cerrada puede reabrirse. Se avisa con el evento alert.reopened.

Reconocer y cerrar desde tu sala#

PUT /v1/alerts/{id} con el scope alerts:write. El cuerpo:

El operador es obligatorio porque «reconocida» mide la respuesta de una persona. En la cronología de la alerta queda «Cliente · Operador (vía integración)».

curl -X PUT https://sandbox.api.safeonuba.com/v1/alerts/0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90 \
  -H "Authorization: Bearer $SAFEONUBA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "resolution_reason": "Falsa alarma",
    "note": "Confirmado por radio con el encargado.",
    "actor": { "name": "E. Ejemplo", "external_id": "OP-117" }
  }'

const res = await fetch(`https://sandbox.api.safeonuba.com/v1/alerts/${alertaId}`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${await tokenSafeOnuba()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    status: 'resolved',
    resolution_reason: 'Falsa alarma',
    note: 'Confirmado por radio con el encargado.',
    actor: { name: operador.nombre, external_id: operador.id },
  }),
});
if (res.status === 409) {
  // Ya estaba cerrada, o la transición no es posible: nada que hacer.
} else if (!res.ok) {
  throw new Error(`${res.status}: ${await res.text()}`);
}

res = requests.put(
    f"https://sandbox.api.safeonuba.com/v1/alerts/{alerta_id}",
    headers={"Authorization": f"Bearer {token_safeonuba()}"},
    json={
        "status": "resolved",
        "resolution_reason": "Falsa alarma",
        "note": "Confirmado por radio con el encargado.",
        "actor": {"name": operador.nombre, "external_id": operador.id},
    },
    timeout=10,
)
if res.status_code != 409:  # 409: ya estaba cerrada
    res.raise_for_status()

var cuerpo = JsonContent.Create(new
{
    status = "resolved",
    resolution_reason = "Falsa alarma",
    note = "Confirmado por radio con el encargado.",
    actor = new { name = operador.Nombre, external_id = operador.Id },
});
var res = await http.PutAsync($"https://sandbox.api.safeonuba.com/v1/alerts/{alertaId}", cuerpo);
if (res.StatusCode != System.Net.HttpStatusCode.Conflict) res.EnsureSuccessStatusCode();

La respuesta es la alerta ya actualizada. Si la transición no es posible —por ejemplo, cerrar o reconocer una alerta ya cerrada— la API responde 409.

Consultar alertas#

GET /v1/alerts devuelve las alertas de la más reciente a la más antigua, paginadas. Filtros:

Para seguir las alertas en tiempo real no consultes en bucle: usa webhooks. La lista sirve para cargar el estado al arrancar y para buscar.

Nombres de los trabajadores#

Los nombres son opcionales por contrato. Si tu contrato no los incluye, worker.name no aparece y title se compone con el tipo, la zona y el identificador de empresa (external_id), sin nombre. Ver Trabajadores y relojes.