API de comandos

Un comando (un RPC) pide a un dispositivo que haga algo y, salvo que sea unidireccional, espera la respuesta del dispositivo. Cada comando se guarda como una solicitud con un estado, para que puedas enviarlo ahora y leer el resultado más tarde. Cómo funcionan los comandos para las personas en la aplicación se explica en Envío de comandos a dispositivos. Las rutas están bajo https://<your host>/tenant/<tenantId>.

En desarrollo: Los comandos a dispositivos detrás de una pasarela (los dispositivos hijos de una pasarela) están en desarrollo. Envía comandos a dispositivos que se conectan por sí mismos.

Rutas

Quién puede enviar qué

Cada comando del catálogo de un perfil tiene un nivel. El nivel determina el permiso:

Así, una clave de API solo puede enviar métodos que estén en el catálogo del perfil del dispositivo.

Enviar un comando

{
    "method": "pump.start",
    "params": {
        "speed": 80
    },
    "timeoutMs": 15000
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices/{deviceId}/rpc' \
  -H 'Content-Type: application/json' \
  -d '{"method":"pump.start","params":{"speed":80},"timeoutMs":15000}'

{
    "rpc": {
        "rpcId": "c0de…",
        "deviceId": "6f1c…",
        "method": "pump.start",
        "status": "SUCCESSFUL",
        "outcome": null,
        "response": {
            "ok": true
        },
        "error": null,
        "tier": "privileged",
        "highImpact": false,
        "source": "api",
        "createdAt": "2026-11-09T09:00:00.000Z",
        "completedAt": "2026-11-09T09:00:01.200Z",
        "…": "…"
    }
}

{
    "rpc": {
        "rpcId": "c0de…",
        "status": "QUEUED",
        "…": "…"
    }
}

{
    "message": "You are not permitted to perform this action",
    "code": "FORBIDDEN"
}

{
    "message": "The device is disabled or quarantined; it takes no commands.",
    "code": "CONFLICT",
    "details": {
        "reason": "device_not_active"
    }
}

{
    "message": "Too many commands to this device; try again in a minute.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
        "reason": "device_rate_limited"
    }
}

• Unidireccional (oneway: true): el comando se completa correctamente cuando se entrega; no se espera respuesta.
• Persistente (persistent: true): si el dispositivo está desconectado, el comando espera a que se conecte durante un máximo de expiresInS y después termina en EXPIRED.
• wait: true fuerza la espera (se rechaza con «A synchronous call waits at most 30 s; use wait: false for a longer timeout.» cuando el comando no puede terminar en 30 s); false responde siempre 202 de inmediato.
• Comandos de alto impacto necesitan "confirm": true y la frase escrita en confirmText cuando el comando del catálogo la tiene. Sin ello: «This command needs confirm: true.» Se registran en el registro de auditoría al enviarse y al terminar, y se envían como máximo una vez.

No hay clave de idempotencia en esta ruta: cada POST crea un nuevo comando. Si tu llamada agota el tiempo de espera en la red, consulta el historial del dispositivo antes de volver a enviar.

Estados

QUEUED → SENT → DELIVERED → SUCCESSFUL, o uno de FAILED, TIMEOUT, EXPIRED, CANCELLED.

outcome añade detalle: running (el dispositivo aceptó un comando de larga duración), unknown (un tiempo de espera agotado) o late (una respuesta llegó después del final). Los resultados se conservan 90 días por defecto.

Leer resultados

Consulta GET /api/iot/rpc/{rpcId} hasta que el estado sea final, o suscríbete a los eventos de webhook rpc.completed y rpc.failed y lee la respuesta cuando llegue. Consulta la Referencia de eventos de webhook.

Historial de un dispositivo, del más reciente al más antiguo:

GET /api/iot/devices/{deviceId}/rpc?status=FAILED&limit=50

Sin page, el historial se lee con un cursor: status, method, from, to (fechas), limit (de 1 a 100, por defecto 25) y cursor. La respuesta es { "requests": [...], "nextCursor": "…" }; pasa nextCursor de vuelta como cursor hasta que sea null. Con page (desde 0), la lista sigue las reglas habituales de listas: pageSize, search, sort (method, status, source, createdAt, completedAt), status y source como listas separadas por comas, createdFrom, createdTo; la respuesta es { "requests": [...], "total": n }. Los parámetros secretos se enmascaran en todas las respuestas.

Cancelar

POST /api/iot/rpc/{rpcId}/cancel pasa un comando QUEUED o SENT a CANCELLED y responde { "rpc": {...} }. Otros estados: 409 «Only a queued or sent request can be cancelled.» Cancelar necesita el mismo permiso de nivel que enviar. Una cancelación no envía webhook.

Límites

Rechazos

El catálogo de comandos

Un comando del catálogo tiene: method, label (hasta 120), description, paramsSchema (hasta 50 campos, cada uno con label, type de text, textarea, number, boolean, select, multi-select o json, y opcionalmente required, min, max, step, options), maskedParams (campos secretos que nunca se muestran de nuevo), tier (basic, privileged, critical), highImpact, oneway, long, defaultTimeoutMs, persistentDefault, confirmText (solo para alto impacto).

{
  "method": "valve.set",
  "label": "Set valve position",
  "tier": "privileged",
  "paramsSchema": { "position": { "label": "Position (%)", "type": "number", "min": 0, "max": 100, "required": true } }
}

GET ...?format=export devuelve { "commands": [...] } sin ids, que PUT acepta de nuevo para copiar un catálogo a otro perfil.