Commands-API

Ein Befehl (ein RPC) fordert ein Gerät auf, etwas zu tun, und wartet, sofern er nicht einseitig ist, auf die Antwort des Geräts. Jeder Befehl wird als Anfrage mit einem Status gespeichert, sodass Sie ihn jetzt senden und das Ergebnis später abrufen können. Wie Befehle für Personen in der App funktionieren, steht unter Befehle an Geräte senden. Pfade liegen unter https://<your host>/tenant/<tenantId>.

In Entwicklung: Befehle an Geräte hinter einem Gateway (die untergeordneten Geräte eines Gateways) sind in Entwicklung. Senden Sie Befehle an Geräte, die sich selbstständig verbinden.

Routen

Wer was senden darf

Jeder Befehl im Katalog eines Profils hat eine Stufe. Die Stufe bestimmt die Berechtigung:

Ein API-Schlüssel kann daher nur Methoden senden, die im Befehlskatalog des Geräteprofils stehen.

Einen Befehl senden

{
    "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"
    }
}

• Einseitig (oneway: true): Der Befehl gilt als erfolgreich, sobald er zugestellt ist; es wird keine Antwort erwartet.
• Persistent (persistent: true): Ist das Gerät offline, wartet der Befehl bis zu expiresInS auf es und endet dann mit EXPIRED.
• wait: true erzwingt das Warten (wird mit „A synchronous call waits at most 30 s; use wait: false for a longer timeout.“ abgelehnt, wenn der Befehl nicht in 30 s abgeschlossen werden kann); false antwortet immer sofort mit 202.
• Folgenreiche Befehle benötigen "confirm": true sowie die eingetippte Phrase in confirmText, wenn der Katalogbefehl eine solche hat. Ohne diese Angaben: „This command needs confirm: true.“ Sie werden beim Senden und beim Abschluss ins Audit-Protokoll geschrieben und höchstens einmal gesendet.

Auf dieser Route gibt es keinen Idempotenzschlüssel: Jeder POST erzeugt einen neuen Befehl. Läuft Ihr Aufruf im Netzwerk in ein Timeout, lesen Sie den Verlauf des Geräts, bevor Sie erneut senden.

Status

QUEUED → SENT → DELIVERED → SUCCESSFUL, oder einer der Werte FAILED, TIMEOUT, EXPIRED, CANCELLED.

outcome liefert Details: running (das Gerät hat einen länger laufenden Befehl angenommen), unknown (ein Timeout) oder late (eine Antwort kam nach dem Ende an). Ergebnisse werden standardmäßig 90 Tage aufbewahrt.

Ergebnisse abrufen

Fragen Sie GET /api/iot/rpc/{rpcId} ab, bis der Status endgültig ist, oder abonnieren Sie die Webhook-Ereignisse rpc.completed und rpc.failed und lesen Sie die Antwort, sobald eines eintrifft. Siehe die Webhook-Ereignisreferenz.

Verlauf eines Geräts, neueste zuerst:

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

Ohne page wird der Verlauf mit einem Cursor gelesen: status, method, from, to (Datumsangaben), limit (1 bis 100, Standard 25) und cursor. Die Antwort ist { "requests": [...], "nextCursor": "…" }; übergeben Sie nextCursor als cursor zurück, bis es null ist. Mit page (ab 0) folgt die Liste den üblichen Listenregeln: pageSize, search, sort (method, status, source, createdAt, completedAt), status und source als kommagetrennte Listen, createdFrom, createdTo; die Antwort ist { "requests": [...], "total": n }. Geheime Parameter werden in jeder Antwort maskiert.

Abbrechen

POST /api/iot/rpc/{rpcId}/cancel setzt einen QUEUED– oder SENT-Befehl auf CANCELLED und antwortet mit { "rpc": {...} }. Andere Status: 409 „Only a queued or sent request can be cancelled.“ Zum Abbrechen wird dieselbe Stufenberechtigung wie zum Senden benötigt. Ein Abbruch sendet keinen Webhook.

Grenzwerte

Ablehnungen

Der Befehlskatalog

Ein Katalogbefehl hat: method, label (bis zu 120), description, paramsSchema (bis zu 50 Felder, jeweils mit label, type von text, textarea, number, boolean, select, multi-select oder json sowie optional required, min, max, step, options), maskedParams (geheime Felder werden nie zurückgegeben), tier (basic, privileged, critical), highImpact, oneway, long, defaultTimeoutMs, persistentDefault, confirmText (nur bei High-Impact-Befehlen).

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

GET ...?format=export gibt { "commands": [...] } ohne IDs zurück, die PUT wieder entgegennimmt, um einen Katalog in ein anderes Profil zu kopieren.