HTTP-API

Die HTTP-API eignet sich für Geräte, die keine Verbindung offen halten können, für Netze, die nur gewöhnliches HTTPS zulassen, und für die Erstinbetriebnahme der Firmware: Anders als bei MQTT antwortet jede Anfrage damit, was die Plattform mit jedem einzelnen Messwert gemacht hat, den Sie gesendet haben.

Basis-URL

https://api.sensocan.com/api/v1

Authentifizierung

Jede Anfrage trägt den Zugriffstoken des Geräts als Bearer-Token:

Authorization: Bearer {DEVICE_ACCESS_TOKEN}

Den Token finden Sie unter Gerätedetails → Token anzeigen. Der Token gehört zu genau einem Gerät, und die URL, an die Sie senden, muss die UUID genau dieses Geräts tragen.

Gerätedetails nach dem Klick auf Token anzeigen: der Dialog mit dem Gerätetoken ist geöffnet, der Zugriffstoken sichtbar und daneben die Schaltfläche zum Kopieren, sodass erkennbar wird, woher der Bearer-Token stammt.

Die Neugenerierung des Tokens sperrt das Gerät aus

Die Aktion zum Neugenerieren im selben Dialog stellt einen neuen Token aus und macht den alten sofort ungültig. Jedes Gerät, das noch den alten Token verwendet, erhält von da an 401, bis Sie den neuen aufspielen.

Header

Header	Wert	Erforderlich
Authorization	Bearer {DEVICE_ACCESS_TOKEN}	Ja
Content-Type	application/json	Ja
Accept	application/json	Empfohlen: Ohne ihn kommt die Antwort auf eine Ratenbegrenzung (rate limit) als HTML-Seite zurück statt als JSON

Endpunkte (endpoints)

1. Ein Messwert für einen Sensor

POST /devices/{device_uuid}/sensors/{sensor}/readings

{sensor} ist entweder der Slug des Sensors oder seine UUID; beide stehen auf der Seite des Sensors.

{
  "data": {
    "value": 25.5,
    "timestamp": "2026-09-03T10:00:00Z"
  },
  "battery_voltage": 3.7
}

Feld	Typ	Erforderlich	Hinweise
data	Objekt	Ja	Genau ein Messwert. Für mehrere den Bulk-Endpunkt verwenden
data.value	Zahl	Ja	Nicht numerische Werte werden abgelehnt
data.timestamp	Zeichenkette nach ISO 8601	Nein	Voreingestellt ist der Zeitpunkt, zu dem die Anfrage eintrifft
battery_voltage	Zahl (Volt), 0–100	Nein	Steht neben data, nicht darin

Jeder weitere Schlüssel in data wird als Metadaten zum Messwert aufbewahrt; siehe dazu die Nutzdatenregeln für beide Protokolle.

2. Mehrere Messwerte für einen Sensor

POST /devices/{device_uuid}/sensors/{sensor}/readings/bulk

{
  "data": [
    { "value": 22.1, "timestamp": "2026-09-03T09:00:00Z" },
    { "value": 22.4, "timestamp": "2026-09-03T09:15:00Z" },
    { "value": 22.8, "timestamp": "2026-09-03T09:30:00Z" }
  ],
  "battery_voltage": 3.6
}

data muss ein Array mit mindestens einem Eintrag sein. Für jeden Eintrag gelten dieselben Regeln wie oben für data.

3. Messwerte für mehrere Sensoren

POST /devices/{device_uuid}/readings

{
  "data": [
    {
      "sensor_slug": "temp_01",
      "value": 25.5,
      "timestamp": "2026-09-03T10:00:00Z"
    },
    { "sensor_uuid": "7a8b9c0d-1234-5678-90ab-cdef12345678", "value": 60.2 },
    { "sensor_slug": "door_01", "value": 1 }
  ],
  "battery_voltage": 3.7
}

Jeder Eintrag benennt seinen eigenen Sensor entweder mit sensor_slug oder mit sensor_uuid; eines von beiden ist erforderlich. Verwenden Sie diesen Endpunkt für ein Gerät mit mehreren Sensoren: Drei einzelne Anfragen erledigen dieselbe Arbeit dreimal.

Was die Antwort Ihnen sagt

Eine Anfrage, mit der mindestens ein Messwert durchgekommen ist, antwortet mit 202 Accepted:

{
  "message": "Readings accepted and queued for rule chain processing.",
  "accepted": 3,
  "duplicates": 0,
  "rejected": {},
  "sensor": "temp_01"
}

Feld	Bedeutung
accepted	An die Regelkette übergebene Messwerte
duplicates	Messwerte, die als Wiederholung von bereits Gesendetem erkannt wurden. Zählen als Erfolg: Einen Puffer erneut zu senden ist unbedenklich
rejected	Aufgetretene Gründe für verworfene Messwerte, mit ihrer Anzahl. Leer ({}), wenn nichts verworfen wurde
sensor	Die Kennung aus der URL, unverändert zurückgegeben. Nur bei den beiden Endpunkten für einen einzelnen Sensor

Auch ein Teilerfolg ist 202: Fünf gesendete Messwerte, davon drei angenommen und zwei abgelehnt, ergeben 202 mit der Aufschlüsselung. Lesen Sie die Zahlen; der Statuscode allein bedeutet nicht „alles ist angekommen“.

„Angenommen“ heißt in der Warteschlange, nicht gespeichert

Ein angenommener Messwert wird an die Regelkette übergeben, die für diesen Sensor gilt, und diese Kette entscheidet, was mit ihm geschieht – auch darüber, ob er gespeichert wird. Eine Kette ohne Speicherschritt führt zu genau diesem Bild: saubere 202-Antworten, und in der Oberfläche sind nirgends Daten zu sehen. Jedes Konto startet mit einer Standard-Regelkette, die speichert; haben Sie eine eigene gebaut, prüfen Sie sie unter Verwaltung → Regelketten.

Ablehnungsgründe

Diese Schlüssel können in rejected auftauchen:

Schlüssel	Bedeutung	Behebung
dropped_unknown_sensor	Die Kennung passte zu keinem Sensor dieses Geräts	Vergleichen Sie sie mit dem Slug und der UUID auf der Seite des Sensors. Der Abgleich ist exakt und unterscheidet Groß- und Kleinschreibung
dropped_missing_identifier	Ein Eintrag im Stapel hatte weder sensor_slug noch sensor_uuid	Geben Sie jedem Eintrag eines von beiden mit
dropped_missing_value	Ein Messwert hatte kein value	Senden Sie value bei jedem Messwert; senden Sie für eine misslungene Messung kein null, sondern lassen Sie sie aus
dropped_invalid_shape	Die Struktur von data passte nicht zum Endpunkt	Senden Sie an den Endpunkt für einen einzelnen Messwert ein Objekt, an die Endpunkte für mehrere ein Array
dropped_future_timestamp	Ein Zeitstempel lag auch nach der Uhrkorrektur noch vor der Serverzeit	Senden Sie einen Zeitstempel nach ISO 8601, oder lassen Sie ihn weg und nutzen Sie die Eintreffzeit
dropped_duplicate	Derselbe Wert für denselben Sensor traf innerhalb des Unterdrückungsfensters erneut ein	Nichts zu beheben. Wird in duplicates gemeldet, nie in rejected

Fehler

Status	Antworttext	Ursache und Behebung
401	{"message":"Device authentication token required.","error":"missing_token"}	Kein Authorization-Header, oder er hat nicht die Form Bearer …
401	{"message":"Invalid device authentication token.","error":"invalid_token"}	Der Token gehört nicht zu dem Gerät in der URL, oder er wurde neu generiert
404	{"message":"Device not found.","error":"device_not_found"}	Die {device_uuid} in der URL gehört zu keinem Gerät. Kopieren Sie sie erneut aus Gerätedetails
404	{"message":"No reading matched a sensor on this device.","error":"sensor_not_found","sensors":["temp_01"]}	Nichts in den Nutzdaten (payload) sprach einen vorhandenen Sensor an. sensors listet die Kennungen auf, die zu nichts passten
422	{"message":"Validation failed.","errors":{"data.value":["The sensor value is required."]}}	Der Anfragetext ist fehlerhaft aufgebaut. errors benennt das betroffene Feld
422	{"message":"No readings were accepted.","error":"no_readings_accepted","rejected":{"dropped_missing_value":2}}	Der Anfragetext war gültig, aber jeder Messwert wurde verworfen. rejected sagt, warum
429	{"message":"Too Many Attempts."}	Ratenbegrenzung erreicht. Stecken Sie zurück und versuchen Sie es erneut, siehe unten

Häufige Ursachen hinter 422 Validation failed: data fehlt oder ist leer, value fehlt oder ist keine Zahl, timestamp ist kein auswertbares Datum, ein Eintrag im Stapel hat weder sensor_slug noch sensor_uuid, battery_voltage liegt außerhalb von 0–100.

Ratenbegrenzung

Das Limit liegt bei 1000 Anfragen pro Minute. Gezählt wird je Quelladresse, mehrere Geräte hinter einem Internetanschluss teilen sich das Kontingent also.

Header	Wann	Bedeutung
X-RateLimit-Limit	Bei jeder Antwort	Der Höchstwert: 1000
X-RateLimit-Remaining	Bei jeder Antwort	Verbleibende Anfragen im laufenden Zeitfenster
Retry-After	Nur bei 429	Sekunden, die vor einem neuen Versuch zu warten sind
X-RateLimit-Reset	Nur bei 429	Wann das Zeitfenster zurückgesetzt wird

Halten Sie sich an Retry-After, statt sofort erneut zu senden, und stecken Sie exponentiell zurück, wenn Sie weiterhin an das Limit stoßen. Kommt ein Gerät dem Limit auch nur nahe, fassen Sie seine Sensoren in einer Anfrage zusammen, statt eine Anfrage je Sensor zu senden.

Vollständiges Beispiel

curl -X POST \
  https://api.sensocan.com/api/v1/devices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/readings \
  -H "Authorization: Bearer your-device-access-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": [
      { "sensor_slug": "temp_01", "value": 25.5 },
      { "sensor_slug": "humidity_01", "value": 60.2 }
    ],
    "battery_voltage": 3.7
  }'

{
  "message": "Readings accepted and queued for rule chain processing.",
  "accepted": 2,
  "duplicates": 0,
  "rejected": {}
}

Antworten in der Firmware verarbeiten

• 202: Leeren Sie Ihren Puffer für alles, was in accepted und duplicates gezählt ist. Ein Messwert in rejected kommt auch bei einem neuen Versuch nicht durch, protokollieren Sie ihn also, statt ihn endlos erneut zu senden.
• 401 und 404: eine Frage der Konfiguration, nichts Vorübergehendes. Stellen Sie die Versuche ein und melden Sie den Fehler dort, wo ihn jemand aus dem Betrieb bemerkt.
• 422: ein Fehler in der Firmware. Protokollieren Sie den Antworttext; er benennt das Feld, das nicht stimmt.
• 429: Warten Sie Retry-After Sekunden und versuchen Sie es dann erneut.
• 5xx oder keine Antwort: vorübergehend. Stecken Sie exponentiell zurück und halten Sie die Messwerte gepuffert; Zeitstempel machen das Nachliefern gepufferter Messwerte exakt, und eine vorgehende Uhr kostet Sie nichts.

Fehlersuche

202-Antworten, aber nirgends Daten. Öffnen Sie Gerätedetails. Die Tabelle Sensoren zeigt für jeden Sensor Aktueller Wert und Zuletzt aktualisiert.

Die Tabelle Sensoren auf Gerätedetails: mindestens ein Sensor mit einem Wert unter Aktueller Wert und einem Zeitpunkt unter Zuletzt aktualisiert, daneben ein Sensor, der noch „Keine Daten“ anzeigt, sodass der Unterschied nebeneinander sichtbar wird.

Wird Zuletzt verbunden aktualisiert, während jeder Sensor „Keine Daten“ anzeigt, speichert die Regelkette die Messwerte nicht: Prüfen Sie Verwaltung → Regelketten. Werden manche Sensoren aktualisiert und andere nicht, passen die Kennungen der stummen Sensoren zu keinem Sensor dieses Geräts, und der Antworttext zu 404 und die Zähler in rejected haben genau das die ganze Zeit gesagt.

Alles antwortet mit 401. Vergewissern Sie sich, dass der Token nicht neu generiert wurde und dass die Device UUID in der URL das Gerät ist, zu dem dieser Token gehört. Ein Token, der bei einem Gerät funktioniert, wird bei einem anderen abgelehnt.

Gepufferte Messwerte kommen als Duplikate zurück. Das ist die erwartete Antwort darauf, einen Puffer erneut zu senden. Behandeln Sie sie als angekommen und geben Sie den entsprechenden Teil Ihres Puffers frei.