Geräte-HTTP-API

Verwenden Sie HTTPS, wenn ein Gerät keine MQTT-Verbindung halten kann: Batteriegeräte, die aufwachen, senden und wieder schlafen, oder Netze, die MQTT blockieren. HTTP-Nachrichten werden genauso verarbeitet wie MQTT-Nachrichten: dieselben Payload-Formen, dieselben Schlüsselregeln, dieselben Ratenlimits und dieselbe monatliche Nachrichtenanzahl. Diese Seite listet jeden Endpunkt auf, den ein Gerät aufrufen kann.

Grundlagen

Das Token wird nie in die URL gesetzt, außer bei Profilen, die Token in der URL aktivieren (siehe unten). Client-Zertifikate werden in der HTTP-API nicht verwendet: Geräte, die sich mit X.509 anmelden, nutzen MQTT. Jeder hier nicht aufgeführte Pfad antwortet mit 404.

Endpunkte

Über HTTP nicht verfügbar: Attribute lesen (GET /api/v1/attributes), auf Änderungen gemeinsamer Attribute warten, das Claim-Fenster öffnen und Firmware anfragen. Diese Pfade antworten mit 404. Geräte, die sie benötigen, verwenden MQTT.

Telemetrie verwendet dieselben Payload-Formen wie MQTT. Siehe MQTT-Topics und Payload-Referenz. Ein Body bei POST /api/v1/telemetry, der kein JSON ist, wird als ein einzelner raw-Schlüssel gespeichert (bis zur Raw-Größe des Profils, standardmäßig 4 KB).

Endpunkt-Details

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

Beispiele

Einen Messwert senden, vom Server mit Zeitstempel versehen:

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}'

Gepufferte Messwerte mit ihren eigenen Zeiten senden (Millisekunden seit 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}}]'

Auf einen Befehl warten und ihn beantworten:

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}}'

Statuscodes

Online-Status für HTTP-Geräte

HTTP-Geräte halten keine Verbindung, daher zeigt ein Profil mit Live-Verbindung sie nie als online an. Geben Sie HTTP-Geräten ein Profil mit Letzte Nachricht (online, solange die letzte Nachricht jünger ist als das erwartete Intervall mal dem Faktor) oder Nur zuletzt gesehen. Siehe Verbindungsstatus und Aktivität.

Geräte, die keine Header senden können

Einige Geräte können keinen Authorization-Header setzen. Aktivieren Sie für diese in dem Profil auf dem Tab Transport & auth die Option Token in the URL. Die Geräte können dann Folgendes verwenden:

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

Befehle über einfaches HTTP

Ein Long Poll, der Hermetry nicht über TLS erreicht, erhält nur die Befehle, die das Profil unter Commands allowed without TLS auflistet. Alle anderen Befehle warten auf eine TLS-Verbindung oder bis sie ablaufen. Ist die Liste leer, antwortet ein einfacher Poll mit 403 tls_required.

Verwandte Themen

• Befehle an Geräte senden
• Gerätezugangsdaten
• Daten kommen nicht an