API de alarmas

Estas rutas permiten que un sistema de tickets, un centro de operaciones o un script trabajen con alarmas. El funcionamiento de las alarmas se explica en Alarms y Working with alarms. Las rutas están bajo https://<your host>/tenant/<tenantId>.

Rutas

Roles predeterminados: leer y reconocer son permisos de User; resolver, silenciar y cambiar reglas son permisos de Admin.

Listar alarmas

GET /api/iot/alarms (las páginas empiezan en 1). Los parámetros desconocidos se rechazan.

Una lista de RESOLVED o any siempre lee un intervalo de tiempo, de como máximo 92 días: «An alarm history range may span at most 92 days.»

{
  "items": [
    {
      "alarmId": "9a7e…",
      "type": "high_temperature",
      "severity": "CRITICAL",
      "status": "OPEN",
      "originator": { "type": "DEVICE", "id": "6f1c…", "name": "cold-room-2" },
      "deviceId": "6f1c…",
      "deviceName": "cold-room-2",
      "profileId": "a1b2…",
      "ruleId": "3c4d…",
      "title": "Temperature too high",
      "details": { "temperature": 9.4 },
      "topic": null,
      "startTs": 1762678800000,
      "openedAt": 1762678800000,
      "acknowledgedAt": null,
      "acknowledgedBy": null,
      "resolvedAt": null,
      "resolvedBy": null,
      "resolveReason": null,
      "occurrences": 3,
      "flapping": false,
      "isAuto": true
    }
  ],
  "total": 1
}

Las horas de las alarmas son milisegundos desde la época. resolveReason es clear (su regla o flujo la despejó), manual (una persona) o originator_deleted (su dispositivo se eliminó).

GET /api/iot/alarms/{alarmId} responde { "alarm": {...} } con los mismos campos más el runbook de la regla. Una alarma de otra organización devuelve 404.

Recuentos

GET /api/iot/alarms/counts?deviceId={deviceId}

{ "open": 4, "acknowledged": 1, "bySeverity": { "CRITICAL": 1, "MAJOR": 2, "MINOR": 0, "WARNING": 2, "INFO": 0 } }

Solo se cuentan las alarmas que no están resueltas. Omita deviceId para toda la organización.

Reconocer y resolver

{
    "alarmIds": [
        "9a7e…",
        "b81f…"
    ],
    "note": "Technician on the way, ticket INC-4411"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/alarms/acknowledge' \
  -H 'Content-Type: application/json' \
  -d '{"alarmIds":["9a7e…","b81f…"],"note":"Technician on the way, ticket INC-4411"}'

{
    "results": [
        {
            "alarmId": "9a7e…",
            "ok": true
        },
        {
            "alarmId": "b81f…",
            "ok": false,
            "reason": "not_active"
        }
    ]
}

POST /api/iot/alarms/resolve acepta el mismo cuerpo y responde de la misma forma. Una alarma resuelta es definitiva; si la condición sigue siendo verdadera, la regla abre una nueva alarma. Resolver manualmente una alarma CRITICAL queda registrado en el registro de auditoría.

Añadir una nota sin cambiar el estado:

POST /api/iot/alarms/{alarmId}/comments
{ "text": "Spare part ordered" }

La respuesta es 201 { "ok": true }. Las notas aparecen en la cronología (GET .../events).

Reglas de alarma

GET /api/iot/alarm-rules/{profileId} responde { "rules": [...] }. PUT reemplaza todo el conjunto de reglas del perfil: las reglas que omita se eliminan, y sus alarmas abiertas se resuelven.

{
  "rules": [
    {
      "type": "high_temperature",
      "title": "Temperature too high",
      "severities": [
        { "severity": "CRITICAL", "condition": { "key": "temperature", "op": ">", "value": { "attribute": "maxTempThreshold" } } },
        { "severity": "WARNING", "condition": { "key": "temperature", "op": ">", "value": 6 } }
      ],
      "debounce": { "mode": "duration", "raise": 300, "clear": 120 },
      "hysteresis": 0.5,
      "notify": { "recipients": [{ "kind": "role", "role": "ADMIN" }], "minSeverity": "WARNING", "repeatEverySec": 3600 },
      "runbook": "Check the door seal, then the compressor."
    },
    {
      "type": "device_offline",
      "title": "Sensor offline",
      "inactivity": { "afterSec": 900, "severity": "WARNING" }
    }
  ]
}

Reglas del esquema:

Las claves de condición se comprueban contra las claves del perfil. El significado completo de cada campo está en Alarm rules on device profiles y Alarm conditions reference.

Silenciamientos

Un silenciamiento debe terminar en el futuro y durar como máximo 90 días. Las alarmas se siguen registrando mientras están silenciadas; no se notifica a nadie. Consulte Muting a device for maintenance.

Errores

Eventos en lugar de sondeo

Suscriba un webhook a alarm.created, alarm.acknowledged y alarm.cleared para conocer los cambios en cuanto ocurren. Los payloads están en la Webhook event reference.