Metingen insturen

Met POST /device/readings stuur je metingen in, tot 1000 per batch. Het antwoord zegt per meting wat de server ermee deed, zodat je weet wat je uit je buffer mag halen.

Een batch#

{
  "batch_uuid": "0d4f6c1e-8a51-4c43-9b6b-3c1f0f7a2e11",
  "readings": [
    {"sensor": "T1", "value": 61.4, "measured_at": "2026-10-08T11:59:00Z"},
    {"sensor": "R2", "value": 10, "measured_at": "2026-10-08T11:59:00Z"},
    {"sensor": "T3", "value": null, "quality": "no_response", "measured_at": "2026-10-08T11:59:00Z"}
  ]
}

Veld	Verplicht	Regel
readings	ja	1 tot 1000 metingen, als lijst
batch_uuid	nee	Een uuid. Houd hem gelijk als je dezelfde batch opnieuw stuurt
clock	nee	Klokanker, alleen voor klokcorrectie: zie Bufferen en de klok

Per meting:

Veld	Verplicht	Regel
sensor	ja	Code uit de configuratie van het apparaat, zoals T1. 1 tot 16 tekens: letters, cijfers, _, . en -. Hoofdlettergevoelig
value	ja, bij ok	Een getal. Mag null zijn of ontbreken als quality niet ok is
quality	nee	ok (standaard), sensor_fault, out_of_range of no_response
measured_at	ja	Wanneer de waarde is gelezen, ISO 8601 met tijdzone
clock_synced, boot_id, mono_ns	nee	Alleen voor klokcorrectie

Dubbel insturen kan geen kwaad#

Een meting is uniek per apparaat, sensor en measured_at, op de seconde. Stuur je hem nog een keer, dan telt hij bij duplicates en blijft de eerste waarde staan, ook als de tweede anders is. Een batch opnieuw sturen na een time-out is dus veilig.

batch_uuid en een Idempotency-Key-header mag je meesturen, maar de server herkent dubbele metingen aan de metingen zelf.

Het antwoord#

Klopt de batch als geheel, dan krijg je 200, ook als er losse metingen zijn afgewezen:

{
  "accepted": 2,
  "duplicates": 0,
  "unmapped": ["T9"],
  "rejected": [{"index": 3, "reason": "measured_at_in_future", "retry": false}]
}

Veld	Betekenis
accepted	Nieuw opgeslagen metingen
duplicates	Metingen die de server al had, ook dubbele binnen deze batch
unmapped	Sensorcodes die niet bij de regelkring van het apparaat horen. Die metingen staan in quarantaine en tellen niet mee in accepted
rejected	Per afgewezen meting: index (plaats in readings, vanaf 0), reason en retry

Haal daarna de hele batch uit je buffer, behalve de afgewezen metingen met retry: true. Die gaan mee in een latere batch.

422 betekent dat de batch als geheel niet klopt: geen of een lege readings, meer dan 1000 metingen, of een ongeldige batch_uuid of clock. Het antwoord heeft een message en per veld de errors. Opnieuw sturen helpt niet: leg de batch apart en zoek de fout.

Afwijzingen per meting#

reason	Betekenis	Wat je doet
invalid_item	De meting is geen object, of clock_synced is geen true of false	Fout in je software: herstellen
invalid_sensor	sensor ontbreekt of past niet in het patroon	Herstellen
invalid_value	value is geen getal, of absoluut groter dan 10⁹	Herstellen
value_required	quality is ok (of ontbreekt) maar er is geen waarde	Geen waarde? Stuur no_response of sensor_fault
invalid_quality	Onbekende waarde voor quality	Een van de vier waarden gebruiken
invalid_measured_at	Geen geldige ISO 8601-tijd met tijdzone, of een datum die niet bestaat	Formaat herstellen
measured_at_in_future	Meer dan 5 minuten na de klok van de server	De klok van je apparaat loopt voor: NTP controleren
measured_at_too_old	Ouder dan 365 dagen	Niets: deze meting kan niet meer mee
clock_unsynced	Gemeten met een ongesynchroniseerde klok, en niet te corrigeren	Bij retry: true bewaren en later opnieuw sturen. Zie Bufferen en de klok
too_many_unknown_sensors	Meer dan 16 verschillende onbekende codes in deze batch	Je sensorcodes controleren
unmapped_quota_exceeded	Vandaag (UTC) al 25 000 metingen in quarantaine gezet	Je sensorcodes controleren
batch_spans_too_many_days	De meting valt op een achtste kalenderdag (UTC) in deze batch	Bewaren (retry: true) en in een volgende batch sturen

Alleen batch_spans_too_many_days, en clock_unsynced zonder gesynchroniseerd klokanker, hebben retry: true. Alle andere afwijzingen zijn definitief.

Onbekende sensoren#

Een code die niet bij de regelkring hoort, gaat 90 dagen in quarantaine. Zo is een fout in de bedrading of de instellingen terug te vinden.

• Je ziet die metingen niet in je grafieken of in het portaal, en je kunt ze niet alsnog aan een sensor koppelen.
• Op de pagina van het apparaat staat onder Fouten in de API-koppeling hooguit eens per uur een regel met het aantal afgewezen metingen en de onbekende codes.
• Codes zijn hoofdlettergevoelig: t1 is niet T1.
• Zonder regelkring is elke code onbekend. Wacht met insturen tot de configuratie sensoren heeft: zie Configuratie ophalen.

Kwaliteit#

quality	Wanneer	Wat ermee gebeurt
ok	Een gewone meting	Telt mee in grafieken, gemiddelden, minima en maxima
sensor_fault	De sensor of regelaar meldt een fout	Opgeslagen, telt niet mee. Blijft het zo, dan volgt na tien minuten de melding Sensorfout
out_of_range	Gelezen, maar buiten wat kan	Stuur de waarde mee. Opgeslagen, telt niet mee
no_response	De sensor of regelaar antwoordde niet	Waarde null. Opgeslagen, telt niet mee

Komt er van een sensor een tijd geen ok binnen (standaard een half uur), dan volgt de melding Sensor geeft geen meting. Beide meldingen zet je per apparaat uit bij Meldingen.

Tijden en waarden#

• measured_at mag hooguit 5 minuten vooruit en 365 dagen terug liggen. De server kapt af op hele seconden en slaat op in UTC.
• Eén batch valt op hooguit 7 kalenderdagen (UTC). Stuur je oudste eerst, dan beslaat een batch hooguit een dag of twee.
• Stuur getallen, absoluut hooguit 10⁹. Een getal als tekst ("61.4") mag ook; andere tekst, true of false geeft invalid_value.
• Uitgangen zoals pompen en kleppen stuur je als getal, zoals de regelaar ze geeft: zie Je eigen BoilerBuddy bouwen.

Alle velden en types staan in de API-referentie.