Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

API de Rules

Lista, crea, prueba, cambia, activa o desactiva, ejecuta y elimina reglas de Rules card por REST, y cambia un lugar entre Manual y Auto.

Estas rutas permiten a un programa gestionar las reglas de la tarjeta Reglas y el modo Manual / Automático de un lugar. Cómo se comportan las reglas para las personas se explica en La tarjeta Reglas y Modos manual y automático. La API de reglas está disponible allí donde está la tarjeta Reglas: viene incluida con Automation.

Las rutas están bajo https://<your host>/tenant/<tenantId>. Envíe Authorization: Bearer <API key> en cada llamada; consulte Autenticación y Fundamentos de la API REST.

Rutas

MétodoRutaPermisoFunción
GET/api/iot/rules?placeType=&placeId=&subtree=iot_rules.readLas reglas de un lugar (y, con subtree=true en un activo, de todo lo que contiene)
GET/api/iot/rules/scope?placeType=&placeId=iot_rules.readLo que una regla de este lugar puede nombrar: sus dispositivos y sus valores, perfiles de dispositivo y sus comandos
POST/api/iot/rules/testiot_rules.readComprueba una regla guardada o sin guardar frente a los valores almacenados ahora; no se ejecuta nada
POST/api/iot/rulesiot_rules.manageCrear una regla
GET/api/iot/rules/{ruleId}iot_rules.readUna regla con su definición y estado
PATCH/api/iot/rules/{ruleId}iot_rules.manageCambiar el nombre o la definición
DELETE/api/iot/rules/{ruleId}iot_rules.manageEliminar la regla y su flujo
POST/api/iot/rules/{ruleId}/enablediot_rules.manageActivar o desactivar la regla
POST/api/iot/rules/{ruleId}/runiot_rules.runEjecutar ahora
GET/api/iot/rules/{ruleId}/runs?limit=iot_rules.readLas ejecuciones más recientes, de la más nueva a la más antigua
GET/api/iot/rule-modes/{placeType}/{placeId}iot_rules.readEl modo del lugar
PUT/api/iot/rule-modes/{placeType}/{placeId}iot_rules.modePoner el lugar en Manual
DELETE/api/iot/rule-modes/{placeType}/{placeId}?applyNow=trueiot_rules.modeVolver a Automático

placeType es asset o device; placeId es el id del activo o del dispositivo.

Permisos y claves de API

PermisoRol por defecto
iot_rules.readUsuario
iot_rules.runUsuario
iot_rules.modeUsuario
iot_rules.manageAdministrador

Una clave de API puede tener los cuatro. Cada llamada también necesita acceso al lugar al que se refiere la regla o el modo, así que sus políticas de acceso pueden restringir a qué lugares llega una clave.

Una regla se guarda como un flujo desplegado en nombre del miembro de la clave, así que la clave también debe tener permiso para hacer lo que hace la regla:

La regla tieneLa clave también necesita
Una acción Enviar un comandoEl permiso de envío de cada nivel que el comando tiene en el catálogo del perfil de dispositivo (iot_rpc.send.basic, iot_rpc.send.privileged, iot_rpc.send.critical)
Un comando de alto impactoautomation.manage_privileged también

La clave no necesita automation.manage para guardar una regla. Sin un permiso necesario, al guardar se responde 403 “No tiene el permiso que necesita esta regla: …”, con los ids que faltan en details.missing. Consulte API de comandos para los niveles.

El objeto regla

{
  "rule": {
    "ruleId": "3c4d…",
    "home": { "type": "asset", "id": "a1b2…" },
    "name": "Fan on when hot",
    "enabled": true,
    "definition": { "v": 1, "when": [], "then": [], "options": { "overlap": "ignore" } },
    "status": "ok",
    "statusReason": null,
    "flowId": "9e8f…",
    "updatedAt": 1762678800000
  }
}
CampoSignificado
homeEl activo o dispositivo al que pertenece la regla. No puede cambiar después de crearla.
enabledEl interruptor propio de la regla. Es independiente de Manual: volver a Automático nunca activa una regla que alguien desactivó.
statusok, o needs_attention cuando se eliminó un dispositivo o lugar que nombra. statusReason explica el motivo con palabras.
flowIdEl flujo en el que se ejecuta la regla. Es de solo lectura en la API de flujos.
updatedAtMilisegundos desde la época

La lista GET /api/iot/rules responde { "rules": [...], "can": {...} }. Cada fila añade lastRun ({ at, text, ok } o null) y nextAt (el próximo inicio en milisegundos para una regla con disparador de hora, fecha o sol; si no, null). can indica lo que puede hacer el llamante aquí: manage, run, mode y sendCommands, cada uno true o false.

La definición

Una definición tiene cuatro partes. Los campos desconocidos se rechazan en todas partes.

{
  "v": 1,
  "when": [ { "id": "hot", "kind": "value", "target": { "device": "6f1c…" }, "key": "temperature", "change": "above", "value": 28, "forSec": 300 } ],
  "onlyIf": { "kind": "time", "after": "08:00", "before": "18:00", "days": [1, 2, 3, 4, 5] },
  "then": [ { "id": "fan", "kind": "command", "target": { "device": "7a2d…" }, "command": "fan.on" } ],
  "options": { "overlap": "ignore" }
}

Cada disparador y acción tiene un id: letras minúsculas, dígitos, - y _, hasta 24 caracteres, único en la regla. Una referencia a dispositivo es { "device": "<deviceId>" } para un dispositivo o { "deviceType": "<deviceProfileId>" } para todos los dispositivos de ese perfil en el ámbito del hogar. Los días de la semana son 1 (lunes) a 7 (domingo). Las horas son HH:MM en la zona horaria del hogar. Las severidades van en minúsculas: critical, major, minor, warning, info.

Cuándo (de 1 a 10 disparadores; cualquiera de ellos inicia la regla)

kindCampos
valuetarget, key, change (any, above, below, equals, not_equals, between, outside), value, value2 (el extremo superior de un rango), forSec (de 0 a 86,400)
statustarget, to (online, offline, inactive)
alarmtarget (una referencia a dispositivo o { "home": true }), event (raised, cleared), minSeverity opcional, alarmType
timeat, days opcional
everyminutes (de 1 a 1,440)
sunevent (sunrise, sunset), offsetMin opcional (de -180 a 180), days
dateat, y daysOfMonth y/o months, o days (no ambos daysOfMonth y days)
manualSin campos: la regla solo se inicia con Ejecutar ahora

Solo si (opcional, una condición)

Una condición es un grupo, { "all": [...] }, { "any": [...] } o { "not": {...} }, o una de estas:

kindCampos
valuetarget, key, op (>, >=, <, <=, ==, !=, between), value, value2
statustarget, is (online, offline)
alarmtarget (o { "home": true }), active (true o false), minSeverity opcional
timeafter, before, days opcionales
sunis (day, night)
datemonths, daysOfMonth, y/o una ventana from y to (MM-DD, ambos o ninguno)
holidayis (true o false): hoy es festivo en el calendario de su organización
exprexpr: una fórmula, de hasta 500 caracteres

El significado de cada una está en Tarjeta Reglas: condiciones y Hora, salida/puesta de sol, fechas y festivos.

Entonces (de 1 a 20 acciones, en orden)

kindCampos
commandtarget, command (un método del catálogo del perfil), params opcional
settingtarget, key, value
notifyrecipients (de 1 a 20 de { "kind": "user", "userId" }, { "kind": "role", "role": "OWNER" } (o ADMIN, USER), { "kind": "team", "teamId" }), text (hasta 1.000 caracteres), channels opcional
alarmop (raise, clear), target (o { "home": true }), alarmType, severity opcional
waitsec (de 1 a 86.400)
wait_untilcondition, timeoutSec (de 1 a 86.400), onTimeout (continue, stop)
choosebranches (de 1 a 5 de { "if": condition, "then": [actions] }), else opcional
ruleop (enable, disable, run), rule (el id de otra regla). run debe ser el último paso.

Lo que hace cada acción está en Rules card: actions; channels se explica en Notifications from rules and flows.

Opciones

CampoValores
overlap (obligatorio)ignore, queue, parallel, restart
maxDe 1 a 10, solo con queue o parallel
runInManualtrue solo para una regla sin comandos, ajustes ni acciones de regla

Crear una regla

POST /api/iot/rules con homeType, homeId, name (de 1 a 120 caracteres), definition y, opcionalmente, enabled (por defecto true) y confirmed.

Una regla que actúa por sí misma, por ejemplo una que envía comandos o cambia ajustes, debe confirmarse. Sin "confirmed": true, dicha regla responde 409 con details.needsConfirmation: true y los motivos en details.reasons, la misma confirmación que pide la tarjeta. Envíala de nuevo con "confirmed": true. Enviar confirmed en cada guardado de una regla que pretendes que actúe es seguro.

curl -X POST "https://<your host>/tenant/<tenantId>/api/iot/rules" \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"homeType":"asset","homeId":"a1b2…","name":"Fan on when hot","confirmed":true,"definition":{"v":1,"when":[{"id":"hot","kind":"value","target":{"device":"6f1c…"},"key":"temperature","change":"above","value":28,"forSec":300}],"then":[{"id":"fan","kind":"command","target":{"device":"7a2d…"},"command":"fan.on"}],"options":{"overlap":"ignore"}}}'

La respuesta es 201 { "rule": {...} }. Una definición con problemas responde 422 con cada problema y la ruta de su fila:

{
  "message": "Type the value to compare with.",
  "code": "VALIDATION_ERROR",
  "details": { "problems": [ { "path": ["when", 0, "value"], "code": "value_missing", "message": "Type the value to compare with." } ] }
}

Lee primero GET /api/iot/rules/scope para conocer los ids de dispositivo, las claves de valor y los comandos del catálogo del lugar. Una regla solo puede nombrar dispositivos dentro del ámbito de su casa.

Probar, cambiar, activar, ejecutar y eliminar

LlamadaCuerpoRespuesta
POST /api/iot/rules/testhomeType, homeId, definition, name opcional{ "result": { "triggers", "conditions", "actions", "mode", "wouldRun", "summary" } }. No se envía ni se escribe nada.
PATCH /api/iot/rules/{ruleId}name y/o definition, confirmed opcional{ "rule": {...} }. Las mismas comprobaciones que al crear.
POST /api/iot/rules/{ruleId}/enabled{ "enabled": true }, confirmed opcional{ "rule": {...} }
POST /api/iot/rules/{ruleId}/runNinguno202 { "accepted": true, "entryId": "…" }. Las condiciones y el modo Manual siguen aplicándose.
GET /api/iot/rules/{ruleId}/runs?limit=20Ninguno{ "runs": [ { "at", "text", "ok" } ] }, por defecto 20, como máximo 30
DELETE /api/iot/rules/{ruleId}Ninguno204

Una regla en needs_attention no puede activarse ni ejecutarse hasta que se guarde de nuevo con una definición válida.

Manual y Auto

GET /api/iot/rule-modes/{placeType}/{placeId} responde:

{ "mode": { "mode": "auto", "effective": "manual", "setOn": { "type": "asset", "id": "a1b2…" }, "until": 1762686000000, "setBy": "5d6e…", "setAt": 1762678800000, "reason": "Pump service" } }

mode es el modo del propio lugar; effective es el que se aplica: Manual cuando el lugar o un activo por encima de él está en Manual; setOn indica ese activo.

  • Manual: PUT con { "until": <milisegundos>, "reason": "…" }. Ambos son opcionales: sin until, Manual dura hasta que alguien lo vuelva a cambiar a Auto. until debe estar en el futuro y dentro de un año; reason admite hasta 500 caracteres. Enviarlo de nuevo sustituye el fin y el motivo.
  • Auto: DELETE. Con ?applyNow=true, las reglas del lugar y de todo lo que hay debajo vuelven a empezar desde los valores guardados ahora; la respuesta { "mode": {...}, "rearmed": n } cuenta lo que se reactivó. Un lugar que sigue a Manual desde un activo superior responde 409.

Errores

EstadoMensaje o motivo
400Validation error con issues: un campo que la ruta no conoce, o un valor con una forma incorrecta. “Elige un fin en el futuro, dentro de un año.”
402QUOTA_EXCEEDED: guardar la regla superaría un límite del plan; details.key indica el límite y details.limit su valor
403“No tienes el permiso que necesita esta regla: …” (details.missing), o la clave o su miembro no pueden usar la ruta o el lugar
404“No se ha encontrado esta regla.” / “No se ha encontrado este lugar.” / “No se ha encontrado este dispositivo.”
409details.needsConfirmation: envía confirmed: true. “Esta regla está desactivada; actívala para ejecutarla.” “Esta regla necesita atención antes de poder ejecutarse.” “La regla cambió mientras la editabas; recárgala y guárdala de nuevo.” “Este lugar sigue a un lugar superior que está en Manual; cambia ese a Auto.”
422details.problems: la definición no se puede guardar. Entre los códigos están value_missing, range_missing, duplicate_id, device_out_of_scope, too_many_devices, bad_param, run_not_last, self_reference, run_in_manual_with_equipment, max_without_queue.
503“No hay ningún worker ejecutando las reglas en este momento, así que la regla no se iniciaría.” (Ejecutar ahora)

El cuerpo de error general y los límites de frecuencia están en Errors and rate limits.

Límites

LímiteValor
Nombre120 caracteres
Disparadores10
Condiciones en un grupo, anidamiento16, 4 niveles
Acciones, incluidas las de dentro de las elecciones20
Ramas de una elección, anidamiento de elecciones5, 2 niveles
forSec, wait, wait_until24 horas
Destinatarios de notificación, texto20, 1.000 caracteres
max ejecuciones en espera o en paraleloDe 1 a 10
Historial de ejecuciones30 ejecuciones
Manual: until, reasonDentro de un año, 500 caracteres

Las reglas cuentan para el límite de reglas de tu plan, no para su límite de flujos. Los demás límites (dispositivos en un ámbito, dispositivos sobre los que actúa una fila) están en The Rules card.

Eventos en lugar de sondeo

Suscribe un webhook a rules.mode_changed (un lugar pasa a Manual, vuelve a Auto o termina su Manual) y a rules.needs_attention (una regla se desactivó porque algo que nombra ya no existe). Los payloads están en la Webhook event reference.