API des commandes

Une commande (un RPC) demande à un appareil d’effectuer une action et, sauf si elle est à sens unique, attend la réponse de l’appareil. Chaque commande est enregistrée comme une requête avec un état, afin que vous puissiez l’envoyer maintenant et lire le résultat plus tard. Le fonctionnement des commandes pour les utilisateurs de l’application est décrit dans Envoyer des commandes aux appareils. Les chemins sont sous https://<your host>/tenant/<tenantId>.

En cours de développement : les commandes vers les appareils derrière une passerelle (les appareils enfants d’une passerelle) sont en cours de développement. Envoyez des commandes aux appareils qui se connectent d’eux-mêmes.

Routes

Qui peut envoyer quoi

Chaque commande du catalogue d’un profil a un niveau. Le niveau détermine la permission :

Ainsi, une clé d’API ne peut envoyer que les méthodes présentes dans le catalogue du profil d’appareil.

Envoyer une commande

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

• Sens unique (oneway: true) : la commande réussit lorsqu’elle est livrée ; aucune réponse n’est attendue.
• Persistante (persistent: true) : si l’appareil est hors ligne, la commande l’attend jusqu’à expiresInS, puis se termine en EXPIRED.
• wait : true impose l’attente (refusé avec « A synchronous call waits at most 30 s; use wait: false for a longer timeout. » lorsque la commande ne peut pas se terminer en 30 s) ; false répond toujours 202 immédiatement.
• Commandes à fort impact nécessitent "confirm": true, et la phrase saisie dans confirmText lorsque la commande du catalogue en comporte une. Sans cela : « This command needs confirm: true. » Elles sont inscrites dans le journal d’audit à l’envoi et à leur fin, et sont envoyées au plus une fois.

Cette route n’a pas de clé d’idempotence : chaque POST crée une nouvelle commande. Si votre appel expire sur le réseau, lisez l’historique de l’appareil avant de renvoyer une commande.

États

QUEUED → SENT → DELIVERED → SUCCESSFUL, ou l’un de FAILED, TIMEOUT, EXPIRED, CANCELLED.

outcome apporte un détail : running (l’appareil a accepté une commande de longue durée), unknown (un délai dépassé) ou late (une réponse est arrivée après la fin). Les résultats sont conservés 90 jours par défaut.

Lire les résultats

Interrogez GET /api/iot/rpc/{rpcId} jusqu’à ce que l’état soit final, ou abonnez-vous aux événements webhook rpc.completed et rpc.failed et lisez la réponse à leur réception. Voir la Référence des événements webhook.

Historique d’un appareil, du plus récent au plus ancien :

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

Sans page, l’historique se lit avec un curseur : status, method, from, to (dates), limit (1 à 100, par défaut 25) et cursor. La réponse est { "requests": [...], "nextCursor": "…" } ; renvoyez nextCursor comme cursor jusqu’à ce qu’il soit null. Avec page (à partir de 0), la liste suit les règles habituelles des listes : pageSize, search, sort (method, status, source, createdAt, completedAt), status et source sous forme de listes séparées par des virgules, createdFrom, createdTo ; la réponse est { "requests": [...], "total": n }. Les paramètres secrets sont masqués dans toutes les réponses.

Annuler

POST /api/iot/rpc/{rpcId}/cancel fait passer une commande QUEUED ou SENT à CANCELLED et répond { "rpc": {...} }. Autres états : 409 « Only a queued or sent request can be cancelled. » L’annulation exige la même permission de niveau que l’envoi. Une annulation n’envoie aucun webhook.

Limites

Refus

Le catalogue de commandes

Une commande du catalogue comporte : method, label (jusqu’à 120), description, paramsSchema (jusqu’à 50 champs, chacun avec label, type valant text, textarea, number, boolean, select, multi-select ou json, et les options required, min, max, step, options), maskedParams (champs secrets jamais réaffichés), tier (basic, privileged, critical), highImpact, oneway, long, defaultTimeoutMs, persistentDefault, confirmText (impact élevé uniquement).

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

GET ...?format=export renvoie { "commands": [...] } sans identifiants, que PUT accepte en retour pour copier un catalogue vers un autre profil.