API HTTP des appareils

Utilisez HTTPS lorsqu’un appareil ne peut pas maintenir une connexion MQTT : appareils sur batterie qui se réveillent, envoient et se rendorment, ou réseaux qui bloquent MQTT. Les messages HTTP sont traités exactement comme les messages MQTT : les mêmes formes de charge utile, les mêmes règles de clés, les mêmes limites de débit, le même nombre mensuel de messages. Cette page répertorie chaque point de terminaison qu’un appareil peut appeler.

Bases

Le jeton ne figure jamais dans l’URL, sauf sur les profils qui activent Token in the URL (voir ci-dessous). Les certificats client ne sont pas utilisés avec l’API HTTP : les appareils qui se connectent avec X.509 utilisent MQTT. Tout chemin non listé ici répond 404.

Points de terminaison

Non disponible via HTTP : lecture des attributs (GET /api/v1/attributes), attente de changements d’attributs partagés, ouverture de la fenêtre de revendication et demande de firmware. Ces chemins répondent 404. Les appareils qui en ont besoin utilisent MQTT.

La télémétrie utilise les mêmes formes de charge utile que MQTT. Voir MQTT topics and payload reference. Un corps de POST /api/v1/telemetry qui n’est pas du JSON est stocké sous une seule clé raw (jusqu’à la taille raw du profil, 4 KB par défaut).

Détails des points de terminaison

{
    "ts": 1759572000000,
    "values": {
        "temperature": 21.5,
        "humidity": 40
    }
}

curl -X POST 'https://<your-host>/api/v1/telemetry' \
  -H 'Content-Type: application/json' \
  -d '{"ts":1759572000000,"values":{"temperature":21.5,"humidity":40}}'

{
    "error": "invalid_payload"
}

{
    "error": "payload_too_large"
}

{
    "error": "rate_limited"
}

{
    "current_fw_title": "boiler-fw",
    "current_fw_version": "26.10.2",
    "lan.ip": "192.168.1.1"
}

curl -X POST 'https://<your-host>/api/v1/attributes' \
  -H 'Content-Type: application/json' \
  -d '{"current_fw_title":"boiler-fw","current_fw_version":"26.10.2","lan.ip":"192.168.1.1"}'

{
    "error": "invalid_payload"
}

{
    "error": "rate_limited"
}

curl -X GET 'https://<your-host>/api/v1/rpc?timeout=20000'

{
    "id": 42,
    "method": "sys.ping",
    "params": {
        "host": "8.8.8.8",
        "count": 3
    }
}

{
    "error": "tls_required"
}

{
    "error": "timeout"
}

{
    "error": "poll_in_progress"
}

{
    "ok": true,
    "result": {
        "sent": 3,
        "received": 3,
        "avg_ms": 18.2
    }
}

curl -X POST 'https://<your-host>/api/v1/rpc/{id}' \
  -H 'Content-Type: application/json' \
  -d '{"ok":true,"result":{"sent":3,"received":3,"avg_ms":18.2}}'

{
    "error": "payload_too_large"
}

{
    "method": "app.request",
    "params": {}
}

curl -X POST 'https://<your-host>/api/v1/rpc' \
  -H 'Content-Type: application/json' \
  -d '{"method":"app.request","params":{}}'

{
    "error": "timeout"
}

{
    "deviceName": "boiler-07",
    "provisionDeviceKey": "pk_8f3b2c1e9d4a7b60",
    "provisionDeviceSecret": "ps_1c9e7f2a4b6d8e03"
}

curl -X POST 'https://<your-host>/api/v1/provision' \
  -H 'Content-Type: application/json' \
  -d '{"deviceName":"boiler-07","provisionDeviceKey":"pk_8f3b2c1e9d4a7b60","provisionDeviceSecret":"ps_1c9e7f2a4b6d8e03"}'

{
    "status": "SUCCESS",
    "credentialsType": "ACCESS_TOKEN",
    "credentialsValue": "aZ3…"
}

{
    "error": "payload_too_large"
}

Exemples

Envoyez une mesure, horodatée par le serveur :

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 21.5, "humidity": 40}'

Envoyez des mesures mises en mémoire tampon avec leurs propres heures (millisecondes depuis 1970, UTC) :

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[{"ts":1759572000000,"values":{"temperature":21.5}},{"ts":1759572060000,"values":{"temperature":21.7}}]'

Attendez une commande et répondez-y :

curl -s "https://<device host>/api/v1/rpc?timeout=30000" -H "Authorization: Bearer <ACCESS_TOKEN>"
# → {"id": 42, "method": "sys.ping", "params": {...}}
curl -X POST "https://<device host>/api/v1/rpc/42" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json" \
  -d '{"ok": true, "result": {"sent": 3, "received": 3}}'

Codes de statut

Statut en ligne des appareils HTTP

Les appareils HTTP ne maintiennent aucune connexion ; un profil avec Live connection ne les affiche donc jamais en ligne. Donnez aux appareils HTTP un profil avec Recent message (en ligne tant que le dernier message est plus récent que l’intervalle attendu multiplié par le facteur) ou Last seen only. Voir Connection status and activity.

Appareils incapables d’envoyer des en-têtes

Certains appareils ne peuvent pas définir un en-tête Authorization. Pour ceux-ci, activez Jeton dans l’URL dans l’onglet Transport & auth du profil. Les appareils peuvent alors utiliser :

POST /api/v1/{token}/telemetry
POST /api/v1/{token}/attributes

Commandes via HTTP non chiffré

Une interrogation longue qui n’atteint pas Hermetry via TLS ne reçoit que les commandes listées dans le profil sous Commandes autorisées sans TLS. Toutes les autres commandes attendent une connexion TLS ou leur expiration. Si la liste est vide, une interrogation simple répond 403 tls_required.

Voir aussi

• Envoi de commandes aux appareils
• Identifiants des appareils
• Les données n’arrivent pas