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étodo | Ruta | Permiso | Función |
|---|---|---|---|
| GET | /api/iot/rules?placeType=&placeId=&subtree= | iot_rules.read | Las 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.read | Lo que una regla de este lugar puede nombrar: sus dispositivos y sus valores, perfiles de dispositivo y sus comandos |
| POST | /api/iot/rules/test | iot_rules.read | Comprueba una regla guardada o sin guardar frente a los valores almacenados ahora; no se ejecuta nada |
| POST | /api/iot/rules | iot_rules.manage | Crear una regla |
| GET | /api/iot/rules/{ruleId} | iot_rules.read | Una regla con su definición y estado |
| PATCH | /api/iot/rules/{ruleId} | iot_rules.manage | Cambiar el nombre o la definición |
| DELETE | /api/iot/rules/{ruleId} | iot_rules.manage | Eliminar la regla y su flujo |
| POST | /api/iot/rules/{ruleId}/enabled | iot_rules.manage | Activar o desactivar la regla |
| POST | /api/iot/rules/{ruleId}/run | iot_rules.run | Ejecutar ahora |
| GET | /api/iot/rules/{ruleId}/runs?limit= | iot_rules.read | Las ejecuciones más recientes, de la más nueva a la más antigua |
| GET | /api/iot/rule-modes/{placeType}/{placeId} | iot_rules.read | El modo del lugar |
| PUT | /api/iot/rule-modes/{placeType}/{placeId} | iot_rules.mode | Poner el lugar en Manual |
| DELETE | /api/iot/rule-modes/{placeType}/{placeId}?applyNow=true | iot_rules.mode | Volver a Automático |
placeType es asset o device; placeId es el id del activo o del dispositivo.
Permisos y claves de API
| Permiso | Rol por defecto |
|---|---|
iot_rules.read | Usuario |
iot_rules.run | Usuario |
iot_rules.mode | Usuario |
iot_rules.manage | Administrador |
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 tiene | La clave también necesita |
|---|---|
| Una acción Enviar un comando | El 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 impacto | automation.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
}
}
| Campo | Significado |
|---|---|
home | El activo o dispositivo al que pertenece la regla. No puede cambiar después de crearla. |
enabled | El interruptor propio de la regla. Es independiente de Manual: volver a Automático nunca activa una regla que alguien desactivó. |
status | ok, o needs_attention cuando se eliminó un dispositivo o lugar que nombra. statusReason explica el motivo con palabras. |
flowId | El flujo en el que se ejecuta la regla. Es de solo lectura en la API de flujos. |
updatedAt | Milisegundos 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)
kind | Campos |
|---|---|
value | target, key, change (any, above, below, equals, not_equals, between, outside), value, value2 (el extremo superior de un rango), forSec (de 0 a 86,400) |
status | target, to (online, offline, inactive) |
alarm | target (una referencia a dispositivo o { "home": true }), event (raised, cleared), minSeverity opcional, alarmType |
time | at, days opcional |
every | minutes (de 1 a 1,440) |
sun | event (sunrise, sunset), offsetMin opcional (de -180 a 180), days |
date | at, y daysOfMonth y/o months, o days (no ambos daysOfMonth y days) |
manual | Sin 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:
kind | Campos |
|---|---|
value | target, key, op (>, >=, <, <=, ==, !=, between), value, value2 |
status | target, is (online, offline) |
alarm | target (o { "home": true }), active (true o false), minSeverity opcional |
time | after, before, days opcionales |
sun | is (day, night) |
date | months, daysOfMonth, y/o una ventana from y to (MM-DD, ambos o ninguno) |
holiday | is (true o false): hoy es festivo en el calendario de su organización |
expr | expr: 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)
kind | Campos |
|---|---|
command | target, command (un método del catálogo del perfil), params opcional |
setting | target, key, value |
notify | recipients (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 |
alarm | op (raise, clear), target (o { "home": true }), alarmType, severity opcional |
wait | sec (de 1 a 86.400) |
wait_until | condition, timeoutSec (de 1 a 86.400), onTimeout (continue, stop) |
choose | branches (de 1 a 5 de { "if": condition, "then": [actions] }), else opcional |
rule | op (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
| Campo | Valores |
|---|---|
overlap (obligatorio) | ignore, queue, parallel, restart |
max | De 1 a 10, solo con queue o parallel |
runInManual | true 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
| Llamada | Cuerpo | Respuesta |
|---|---|---|
POST /api/iot/rules/test | homeType, 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}/run | Ninguno | 202 { "accepted": true, "entryId": "…" }. Las condiciones y el modo Manual siguen aplicándose. |
GET /api/iot/rules/{ruleId}/runs?limit=20 | Ninguno | { "runs": [ { "at", "text", "ok" } ] }, por defecto 20, como máximo 30 |
DELETE /api/iot/rules/{ruleId} | Ninguno | 204 |
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:
PUTcon{ "until": <milisegundos>, "reason": "…" }. Ambos son opcionales: sinuntil, Manual dura hasta que alguien lo vuelva a cambiar a Auto.untildebe estar en el futuro y dentro de un año;reasonadmite 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 responde409.
Errores
| Estado | Mensaje o motivo |
|---|---|
| 400 | Validation 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.” |
| 402 | QUOTA_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.” |
| 409 | details.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.” |
| 422 | details.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ímite | Valor |
|---|---|
| Nombre | 120 caracteres |
| Disparadores | 10 |
| Condiciones en un grupo, anidamiento | 16, 4 niveles |
| Acciones, incluidas las de dentro de las elecciones | 20 |
| Ramas de una elección, anidamiento de elecciones | 5, 2 niveles |
forSec, wait, wait_until | 24 horas |
| Destinatarios de notificación, texto | 20, 1.000 caracteres |
max ejecuciones en espera o en paralelo | De 1 a 10 |
| Historial de ejecuciones | 30 ejecuciones |
Manual: until, reason | Dentro 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.

