MQTT-export datamodel en payloadformat

Deze technische pagina beschrijft het exacte MQTT-API van de MQTT-export functie in Workspaces. Je gebruikt dit formaat wanneer je een subscriber, parser of data pipeline bouwt die EnergieID-berichten consumeert.

Klaar om jouw broker te linken aan EnergieID? Voor configuratiestappen, rechten en foutmeldingen, ga naar MQTT-export.

Basisbegrippen

• Workspace: de omgeving van een organisatie in EnergieID.
• Record: een dossier binnen een Workspace, meestal een gebouw of installatie.
• Meter: een tijdsreeks binnen een dossier (bijvoorbeeld gasverbruik, zonneproductie, batterijopslag).
• Device (twin): een gekoppeld toestel of datapunt dat realtime berichten kan aanleveren.
• Channel: een meetkanaal binnen toesteldata (key-value), bijvoorbeeld vermogen, spanning, stroom of temperatuur.

Welke datastromen bestaan er?

• Meterdata: Verwerkte meterlezingen uit het dossier. Deze data is niet realtime en wordt periodiek gepubliceerd. De frequentie hangt af van de integratie en het type meter.
• Apparaatgegevens: Realtime device-data per koppeling/integratie. Niet alle integraties leveren realtime data; sommige integraties publiceren alleen meterdata.

Alle apparaatgegevens worden ook gepubliceerd als meterdata (eventueel geagregeerd na verwerking), maar niet alle meterdata wordt gepubliceerd als apparaatgegevens, omdat niet alle integraties realtime data leveren. Voor analyses is het dus beter om de meterdata te gebruiken, omdat deze vollediger is. Als je echter een realtime dashboard wilt bouwen, gebruik dan de apparaatgegevens.

Meterdata

Standaardtopic: energyid/workspace/{{workspaceId}}/record/{{recordNumber}}/meter/{{meterId}}

Meterdata wordt als een JSON-object gepubliceerd met metagegevens en een data-array.

{
  "workspaceId": "7e8f2f7e-2c9f-4e90-bf2e-8e1c6b6f5f6c",
  "recordNumber": "EA-1234567",
  "meterId": "3c2a6b8f-7f0a-45b4-9d4a-6f73b30e30aa",
  "metric": "electricityImport",
  "unit": "kWh",
  "readingType": "PostmarkedInterval",
  "interval": "PT15M",
  "data": [
    {
      "timestamp": "2026-08-06 10:15:00+02:00",
      "value": 1.42,
      "min": 1.21,
      "max": 1.55,
      "mean": 1.39
    }
  ]
}

Velden

• workspaceId: GUID van de Workspace.
• recordNumber: dossiernummer.
• meterId: GUID van de meter.
• metric: metriekcode, duidt aan wat er wordt gemeten.
• unit: eenheid die bij die metriek hoort.
• readingType: type meting, verduidelijkt hoe je een meetwaarde moet interpreteren (bijvoorbeeld Counter, Gauge).
• interval: ISO-8601 periodiciteit van meting (bijvoorbeeld PT5M, PT15M, PT1H, P1D) of manual voor niet periodieke metingen.
• data[].timestamp: timestamp met offset.
• data[].value: hoofdwaarde van de meting.
• data[].min / max / mean: alleen relevant bij gaug-data; kan ontbreken of null zijn bij andere types.

Belangrijk: De velden metric, unit en readingType zijn Enums, er is dus een vaste set aan mogelijke waardes. Voor een up-to-date overzicht van alle mogelijke waardes, raadpleeg de API-documentatie van meterresources: EnergyID API reference - Meters.

Apparaatgegevens

Standaardtopic: energyid/workspace/{{workspaceId}}/record/{{recordNumber}}/device/{{twinId}}

Apparaatdata wordt per event als JSON gepubliceerd.

{
  "recordNumber": "EA-1234567",
  "twinId": "f2a13f6d-1d7a-4f14-b5e8-a53c9f638f1c",
  "timestamp": 1754477700,
  "channels": {
    "pwr": 430.2,
    "el": 230.1
  }
}

Velden

• recordNumber: dossiernummer
• twinId: GUID van het toestel/digital twin.
• timestamp: Unix timestamp (seconden).
• channels: key-value map met meetkanalen en numerieke waarden.

Channels in detail

De exacte keys in channels hangen af van het type toestel en de gekoppelde integratie. EnergieID behandelt channels als een flexibele meetset, waardoor de keyset kan verschillen per bericht of per toesteltype.

Typische eigenschappen van channels:

• Elke key is een meetnaam (bijvoorbeeld el, pwr, bat, heat).
• Elke value is numeriek (floating point).
• Niet alle keys zijn altijd aanwezig; subscribers moeten defensief omgaan met ontbrekende of extra keys.
• Betekenis en eenheid van een channel-key zijn integratie- en toestelafhankelijk.

Hieronder vind je een lijst van standaard kanalen en hoe wij deze mappen in onze systemen:

QoS en retain-gedrag

• Berichten worden gepubliceerd met QoS AtLeastOnce (QoS 1).
• Voor meterdata gebruikt de publisher een retain-vlag, zodat de laatst bekende payload op het topic bewaard kan blijven door de broker.
• Voor realtime apparaatgegevens wordt niet retained gepubliceerd.

Fouten en robuustheid

• Bij connectie- of publishfouten logt EnergieID een broker-specifieke leveringsfout in de Workspace-instellingen.
• Na een fout probeert de publisher opnieuw met een verse verbinding.
• Bij de eerste fout krijgt een Workspace-beheerder een bericht in het berichtencentrum.