Public API handleiding

Introductie

De openbare HUB API biedt een programmatische interface naar het HUB-platform, waarmee integratie met zowel het HUB-portaal als Embion EMS-controllers mogelijk is. Via deze API kunnen gebruikers gegevens ophalen zoals installatie-informatie, meterstanden en omvormergegevens. Daarnaast biedt de API eindpunten voor het aansturen van EMS-controllers, waarmee gebruikers deze op afstand kunnen beheren.

Doel

Het doel van dit document is om uitgebreide documentatie te bieden voor de openbare HUB API, inclusief gedetailleerde informatie over authenticatiemethoden, API-eindpunten, verzoek- en antwoordformaten en gebruiksvoorbeelden.

Beoogd publiek

Dit document is bedoeld voor ontwikkelaars en integrators die met de openbare HUB API moeten werken, evenals voor technische belanghebbenden die inzicht nodig hebben in de mogelijkheden en het gebruik van de API.

Algemene informatie

HTTP-statuscodes

De openbare HUB API gebruikt standaard HTTP-statuscodes om het succes of falen van API-verzoeken aan te geven. De volgende statuscodes worden veelgebruikt:

HTTP-statuscodes
Code Status Beschrijving
200 OK Het verzoek was succesvol en het antwoord bevat de gevraagde gegevens
400 Bad Request Het verzoek was ongeldig of onjuist opgesteld
401 Unauthorized Authenticatie is vereist en het verzoek is niet toegepast omdat geldige authenticatiegegevens ontbreken
403 Forbidden De server heeft het verzoek begrepen maar weigert het te autoriseren
404 Not Found De gevraagde bron kon niet worden gevonden
500 Internal Server Error Er is een fout opgetreden op de server bij het verwerken van het verzoek

ISO 8601

De openbare HUB API gebruikt de ISO 8601-standaard voor datum- en tijdweergave.

Aanbevolen formaten (UTC)
Formaat Voorbeeld Beschrijving
Volledig tijdstempel 2022-12-14T08:00:00Z UTC-tijdstempel (aanbevolen)
Met milliseconden 2022-12-14T08:00:00.000Z UTC-tijdstempel met milliseconden
Alleen datum 2022-12-14 Geïnterpreteerd als 2022-12-14 00:00:00 UTC
Opmerking

Belangrijke opmerkingen:

  • Voeg altijd het Z-achtervoegsel of een expliciete offset toe (bijv.: +01:00) bij het opgeven van een tijdcomponent.
  • Alle tijdstempels in API-antwoorden worden geretourneerd in UTC met het Z-achtervoegsel.

Content Type

De openbare HUB API ondersteunt uitsluitend het JSON-formaat voor zowel verzoeken als antwoorden. Alle gegevens die met de API worden uitgewisseld, moeten als JSON zijn gecodeerd, en clients moeten de header Content-Type: application/json instellen bij het verzenden van verzoeken.

GZIP-compressie

De openbare HUB API ondersteunt GZIP-compressie voor verzoek- en antwoordbody’s. Clients kunnen GZIP-compressie aanvragen door de header Accept-Encoding: gzip in hun verzoeken op te nemen. Als de server GZIP-compressie ondersteunt, antwoordt deze met een header Content-Encoding: gzip en wordt de antwoordbody gecomprimeerd met GZIP.

Snelheidsbeperking

De API hanteert dagelijkse verzoeklimieten die om middernacht UTC worden gereset. Bij gebruik van apparaattoegangstokens bevatten antwoorden headers die de huidige status van je snelheidsbeperking aangeven:

Headers voor snelheidsbeperking
Header Beschrijving
RateLimit-Limit Maximaal aantal toegestane verzoeken per dag
RateLimit-Remaining Aantal resterende verzoeken in de huidige periode
RateLimit-Reset Seconden tot de snelheidsbeperking wordt gereset (om middernacht UTC)

Je specifieke limiet is afhankelijk van je tokenconfiguratie. Wanneer de limiet wordt overschreden, retourneert de API HTTP-statuscode 429 Too Many Requests.

Authenticatie

Alle API-eindpunten vereisen authenticatie via toegangstokens. De openbare API ondersteunt twee authenticatiemethoden: apparaattoegangstokens en toegangstokens van derden.

Apparaattoegangstokens

Apparaattoegangstokens kunnen worden gegenereerd in het HUB-portaal en corresponderen altijd met een specifieke Embion EMS-controller. Deze tokens kunnen worden gebruikt om gegevens van de controller op te halen en om deze aan te sturen. Er kunnen meerdere tokens voor één controller worden aangemaakt.

Aanmaken

Apparaattoegangstokens kunnen worden aangemaakt in de Apparaten-app van het HUB-portaal. Raadpleeg voor meer informatie over het aanmaken van apparaattoegangstokens het gedeelte over apparaattoegangstokens in de documentatie van het HUB-portaal.

Rechten en limieten

Verzoeklimieten
Opmerking

Neem contact op met Embion als er meer dan 10.000 verzoeken per apparaat per dag nodig zijn, voor verdere ondersteuning en om specifieke behoeften te bespreken.

Er geldt een standaardlimiet van 10.000 verzoeken per apparaat per dag, waarbij elk verzoek meetelt voor deze limiet. Apparaattokens kunnen ook worden geconfigureerd met een specifieke maximale verzoeklimiet, die lager dan of gelijk aan de dagelijkse apparaatlimiet moet zijn, aangezien alle verzoeken nog steeds bijdragen aan deze limiet.

Verloop en intrekking

Apparaattoegangstokens verlopen standaard niet, maar een vervaldatum kan worden geconfigureerd in het HUB-portaal. Daarnaast kunnen apparaattokens daar tijdelijk worden uitgeschakeld of ingetrokken.

Rechten

Apparaattoegangstokens kunnen worden geconfigureerd met specifieke rechten, die bepalen welke acties met het token kunnen worden uitgevoerd. Deze rechten kunnen worden ingesteld bij het aanmaken van het token en later worden gewijzigd indien nodig.

Regelingstoegang: Dit recht stelt het token in staat om de bijbehorende EMS-controller aan te sturen, bijv. door installatieregelingsopdrachten te versturen.

Alle UID’s toestaan: Embion EMS-controllers monitoren en besturen assets zoals PV-omvormers, batterijen en meters met behulp van unieke identificatoren (UID’s). Dit recht geeft het token toegang tot het monitoren van alle assets die aan de controller zijn gekoppeld. Als dit recht niet is verleend, kan het token alleen assets monitoren die expliciet zijn toegewezen via hun UID’s.

Gebruik

Apparaattoegangstokens bestaan uit twee delen: een id en de daadwerkelijke tokenwaarde. Het id is een unieke identificator voor het token, terwijl de tokenwaarde een lange tekenreeks is die wordt gebruikt om API-verzoeken te authenticeren. Zowel het id als de tokenwaarde zijn vereist voor authenticatie. Als er een mismatch tussen beide is, wordt het verzoek afgewezen en wordt een antwoord met statuscode 401 - Unauthorized geretourneerd.

Om API-verzoeken correct te authenticeren met een apparaattoegangstoken, moet de tokenwaarde worden opgenomen in de API-KEY-header van het verzoek. Bijvoorbeeld: API-KEY: 1nsq2001is51dXmaz6xmc8Xmla10rf109lsyb1Xyopape.

Het id moet ook in het verzoek worden opgenomen. De manier waarop dit wordt gedaan, verschilt per verzoek. Voor GET-verzoeken moet het als queryparameter worden meegegeven. Voor andere verzoektypen moet het id in de verzoekbody worden opgenomen.

Voorbeeld met een queryparameter (toegevoegd aan de URL van het verzoek):

https://api.hub.embion.nl/v1/status?id=1nsq2001is51d

Voorbeeld verzoekbody:

{
"id": "1nsq2001is51d"
}

Toegangstokens van derden

Toegangstokens van derden stellen een geautoriseerde derde partij in staat om EMS-controllers te monitoren en/of aan te sturen waartoe gebruikers toegang hebben verleend. In vergelijking met apparaattoegangstokens zijn deze eenvoudiger in gebruik en beheer, aangezien dezelfde tokenwaarde kan worden gebruikt om alle gekoppelde apparaten te benaderen. Daarnaast kunnen gebruikers toegang tot specifieke apparaten verlenen zonder apparaattoegangstokens aan te maken en te delen, wat het proces vereenvoudigt.

Aanmaken

Belangrijk

Toegangstokens van derden worden aangemaakt en beheerd door Embion. Neem contact met ons op als je een toegangstoken van derden wilt aanmaken voor verdere ondersteuning.

Nadat je derde partij is geregistreerd, kunnen gebruikers apparaattoegang aan jou verlenen in de Apparaten-app van het HUB-portaal.

Rechten en limieten

Verzoeklimieten

Toegangstokens van derden hebben geen expliciete verzoeklimieten.

Verloop en intrekking

Toegangstokens van derden verlopen standaard niet, maar een vervaldatum kan indien nodig door Embion worden geconfigureerd. Daarnaast kunnen tokens van derden tijdelijk worden uitgeschakeld of ingetrokken.

Rechten

Derde partijen en hun bijbehorende tokens kunnen de volgende rechten hebben:

Monitoring: Dit recht stelt de derde partij in staat om de bijbehorende EMS-controller en de assets ervan te monitoren (altijd actief).

Regeling: Dit recht stelt de derde partij in staat om de bijbehorende EMS-controller en de assets ervan aan te sturen (optioneel).

Er is slechts één derde partij met Regeling-toegang toegestaan per EMS-controller. Er is geen limiet op het aantal derde partijen met Monitoring-toegang.

Gebruik

Third party access tokens consist of two parts, an id and the actual token value. The ID is a unique identifier for either the token itself or a connected EMS Controller, while the token value is a long string of characters that is used to authenticate API requests. Both the ID and the token value are required for authentication. If there is a mismatch between them, the request will be rejected and a response with status code 401 - Unauthorised will be returned.

In order to fetch the IDs of connected EMS Controllers, please refer to the third party information API endpoints.

In order to correctly authenticate API requests using a third party access token, the token value must be included in the API-KEY-THIRD-PARTY header of the request. For example: API-KEY-THIRD-PARTY: 1nsq2001is51dXmaz6xmc8Xmla10rf109lsyb1Xyopape.

The ID must also be included in within the request. The way this is done differs per request. For GET requests, it must be passed as a query parameter. For other request types, the id should be included in the request body.

Example with a query parameter (appended to the URL of the request):

https://api.hub.embion.nl/v1/status?id=1nsq2001is51d

Example request body:

{
"id": "1nsq2001is51d"
}

API-eindpunten

Algemene apparaatinformatie

GET apparaatstatus

Method: GET | URL: https://api.hub.embion.nl/v1/status

This endpoint returns information about the current status of a specific device.

Required permissions

Device tokens: (all allowed) Third party tokens: Monitoring

Request

Query parameters

GET device status query parameters
VAR Description Mandatory
ID The ID of the token (device tokens) or the device (third party tokens) to retrieve status information for. Yes

Example request

https://api.hub.embion.nl/v1/status?id=[id]
Response
Response body parameters
VAR Description Format
status actual status of the plant string
online true if plant is online, false if offline (no data or status received in the last 2 minutes) bool
last_contact last contact in ISO 8601 layout string
serial serial number of device string
version actual software version of device string
pn product number of device string
name reference name of device string
ems_site EMS Site location of device string
status_message returns the actual status message of the device string
support_status returns the actual support status, disabled or support ID when enabled string
safe_state true if safe_state is enabled on the device bool
plant_control idle, pending, sent, accepted, failed string
epex_configured true if the device has energy price control rules (defined in the energy pricing app), false if not bool
token token data (only included when a device token was used, see table below) token

Definition of token:

Definition of token
VAR Description Format
control_allowed true if control access is enabled for the given token bool
expire_date expiration date of the given token if set string
request_limit maximum daily requests for the token when configured, otherwise the configured maximum device requests (default 10.000) Integer
requests_today_token number of requests done for the token today Integer

Example response body

 {
    "status": "ok",
    "online": true,
    "last_contact": "2022-12-14T12:48:13.000Z",
    "serial": "0100211001090B",
    "version": "1.3.1",
    "pn": "GSE-A010-POE",
    "name": "main-solar",
    "ems_site": "Embion",
    "status_message": "reducing inverters",
    "support_status": "A291D88",
    "safe_state": false,
    "plant_control": "idle",
    "epex_configured": false,
    "token": {
        "control_allowed": true,
        "expire_date": "2024-09-30T00:00:00.000Z",
        "request_limit": 10000,
        "requests_today_token": 40
    }
}

GET UID’s

Methode: GET | URL: https://api.hub.embion.nl/v1/uids

Dit eindpunt retourneert alle UID’s die beschikbaar zijn voor het opgegeven token. Het resultaat kan alle UID’s of een subset van UID’s bevatten, afhankelijk van de configuratie van het token.

Vereiste rechten

Apparaattokens: (alles toegestaan)

Tokens van derden: Monitoring

Tokens van derden hebben altijd toegang tot alle UID’s van het apparaat.

Verzoek

Queryparameters

GET UID’s queryparameters
VAR Beschrijving Verplicht
ID Het ID van het token (apparaattokens) of het apparaat (tokens van derden) waarvoor statusinformatie moet worden opgehaald. Ja
isonline Wanneer true, worden alleen UID’s geretourneerd die in de afgelopen twee dagen online waren. Standaard is false. Nee

Voorbeeldverzoek

https://api.hub.embion.nl/v1/uids?id=[id]&isonline=true
Antwoord

Antwoordparameters

Antwoordparameters
VAR Beschrijving Formaat
allowall Geeft aan of het token toegang heeft tot alle UID’s boolean
isonline Geeft aan of online of offline UID’s worden geretourneerd boolean
uids De lijst met UID’s die aan het apparaat zijn gekoppeld array

Voorbeeld antwoordbody

{
  [  
        "allowall": true,
        "isonline": false,
        "uids": [
          "ev1_Parkeerplaats P1:21",
          "inverter1_Dak:31",
          "meter1_grid:1"
      ]
  ]
}

Gegevensophaling

GET installatiegegevens

Methode: GET | URL: https://api.hub.embion.nl/v1/plant

Dit API-eindpunt retourneert gegevens van de opgegeven installatie.

Vereiste rechten

Apparaattokens: (alles toegestaan)
Tokens van derden: monitoring

Verzoek

Queryparameters

Opmerking

Laatste waarde

De laatste datameting is alleen beschikbaar binnen de afgelopen twee uur. Als zowel de startdatum als de periode niet zijn gedefinieerd in het verzoek, wordt alleen de laatste datameting geretourneerd als er gegevens beschikbaar zijn; anders worden er geen gegevens geretourneerd.

Tip

Datatijdsbereik

  • Gebruikers kunnen optioneel een tijd toevoegen aan de start_date, wat het daginterval verschuift. Het totale aantal geretourneerde vermeldingen blijft echter ongewijzigd. Als er geen tijd is opgegeven, loopt een dag van 00:00:00 tot 23:59:59 in de geselecteerde tijdzone.
  • De start_date bepaalt het begin van het data-range. De period definieert het interval tussen geretourneerde datums, terwijl het range de einddatum/-tijd relatief aan start_date specificeert en zo het aantal geretourneerde vermeldingen bepaalt.
Opmerking

Periodebeperkingen

Houd er rekening mee dat er beperkingen zijn bij het combineren van periode en bereik

  • Voor periode q (per kwartier) en h (per uur) is het maximale bereik d (één dag).
  • Voor periode d (dagelijks) is het maximale bereik w (één week).
  • Voor periode w (wekelijks) is het maximale bereik m (één maand).
  • Voor periode m (maandelijks) is het maximale bereik y (één jaar).
GET installatiegegevens queryparameters
VAR Beschrijving Verplicht Formaat
ID ID van het token (gegenereerd in de HUB) Ja String
period Selecteer gegevensretourperiode:
l - laatste meting (standaard)
q - 15 minuten
h - per uur
w - wekelijks
d - dagelijks
m - maandelijks
y - jaarlijks
Nee String
range Tijdsbereik om weer te geven:
d - dag (standaard)
w - week
m - maand
y - jaar
Nee String
type Combinatietype van meerdere datapunten:
min - minimale waarde in tijdsbereik
max - maximale waarde in tijdsbereik (standaard)
avg - gemiddelde waarde in tijdsbereik
Nee String
start_date Datum van de eerste meting in ISO 8601-indeling, als niet ingesteld wordt de huidige dag gebruikt Nee String

Voorbeeldverzoek

https://api.hub.embion.nl/v1/plant?id=[id]&period=q&range=d&type=max&start_date=2022-12-14
Antwoord

Antwoordparameters De installatiegegevens zijn opgenomen in de JSON-body van het antwoord. De exacte opmaak van de body varieert afhankelijk van de queryparameters in het verzoek.

De volgende parameters kunnen aanwezig zijn, als de gegevens beschikbaar zijn:

Antwoordparameters
VAR Beschrijving Eenheden Formaat
timestamp Tijdstempel van de meting ISO 8601 string
psol Actueel zonnevermogen 1 W Integer
kdy Cumulatieve dagelijkse opbrengst 1 Wh Integer
kty Cumulatieve totale opbrengst 1 Wh Integer
soc Gemiddelde laadtoestand 0.1% Integer
evku Cumulatief EV-laderverbruik 1 Wh Integer
pev Totaal EV-ladervermogen 1 W Integer
pbat Totaal batterijvermogen 1 W Integer
run # omvormers in RUN-status - Integer
warn # omvormers in WARN-status - Integer
err # omvormers in ERR-status - Integer
red Actuele reductiewaarde (10000 == 100% => geen reductie) Vertegenwoordigt vermogenslimiet % Integer
var1 Vrij te gebruiken variabele - Integer
var2 Vrij te gebruiken variabele - Integer
var3 Vrij te gebruiken variabele - Integer
var4 Vrij te gebruiken variabele - Integer
in1 Status van digitale ingang 1 - Integer 0 of 1 (bool)
in2 Status van digitale ingang 2 - Integer 0 of 1 (bool)
out1 Status van digitale uitgang 1 - Integer 0 of 1 (bool)
out2 Status van digitale uitgang 2 - Integer 0 of 1 (bool)
con # omvormers verbonden met de gateway - Integer
pgrid netvermogen 1 W Integer
egi Net-importenergie 1 Wh Integer
ege Net-exportenergie 1 Wh Integer
gil1 Netfase 1 stroom 0.1 A Integer
gil2 Netfase 2 stroom 0.1 A Integer
gil3 Netfase 3 stroom 0.1 A Integer
gul1 Netfase 1 spanning 0.1 V Integer
gul2 Netfase 2 spanning 0.1 V Integer
gul3 Netfase 3 spanning 0.1 V Integer

Voorbeeld antwoordbody

{
  [
    "timestamp": "2022-12-14T10:00:00.000Z",
    "con": 3,
    "ege": 3500,
    "egi": 2000,
    "err": 0,
    "in1": 1,
    "in2": 0,
    "out1": 0,
    "out2": 0,
    "gil1": 5,
    "gil2": 6,
    "gil3": 7,
    "gul1": 220,
    "gul2": 230,
    "gul3": 240,
    "kdy": 1010,
    "kty": 7200,
    "pgrid": 1000,
    "psol": 1750,
    "soc": 550,
    "pbat": 1550,
    "pev": 750,
    "evku": 2450,
    "red": 10000,
    "run": 2,
    "var1": 1,
    "var2": 2,
    "var3": 3,
    "var4": 4,
    "warn": 1
  ],
  [
    "timestamp": "2022-12-14T10:15:00.000Z",
    "con": 3,
    "ege": 4100,
    "egi": 2000,
    "err": 0,
    "in1": 1,
    "in2": 0,
    "out1": 0,
    "out2": 0,
    "gil1": 56,
    "gil2": 63,
    "gil3": 78,
    "gul1": 2218,
    "gul2": 2301,
    "gul3": 2368,
    "kdy": 12010,
    "kty": 7200,
    "pgrid": -11600,
    "psol": 2000,
    "soc": 550,
    "pbat": -15000,
    "pev": 750,
    "evku": 2450,
    "red": 10000,
    "run": 3,
    "var1": 1,
    "var2": 2,
    "var3": 3,
    "var4": 4,
    "warn": 0
  ]
}

GET metergegevens

Method: GET | URL: https://api.hub.embion.nl/v1/meter

This API endpoint returns individual meter data.

Required permissions

Device tokens: (all allowed)
Third party tokens: monitoring

Request

Query parameters

Opmerking

Last value

Note that the last data sample is only available within the last two hours. If both the start date and period are not defined in the call, only the last data sample is returned if data is available; otherwise, no data will be returned.

Tip

Data time range

  • Users can optionally include a time with the start_date, which shifts the day interval. However, the total number of returned entries remains unchanged. If no time is specified, a day is considered from 00:00:00 to 23:59:59 in the selected timezone.
  • The start_date determines the beginning of the data range. The period defines the interval between returned dates, while the range specifies the end date/time relative to start_date, thereby determining the number of entries returned.
Opmerking

Period limitations

Please note there are some limitations when combining period and range

  • For period q (quarter-hourly) and h (hourly), the maximum range is d (one day).
  • For period d (daily), the maximum range is w (one week).
  • For period w (weekly), the maximum range is m (one month).
  • For period m (monthly), the maximum range is y (one year).
GET meter data query parameters
VAR Description Mandatory Format
ID ID of the token (generated in the HUB) Yes String
uid the uid of the meter to read, only one uid can be entered Yes String
period Select data return period:
l - last sample (default)
q - 15 minute
h - hourly
w - weekly
d - daily
m - monthly
y - yearly
No String
range Time range to show:
d - day (default)
w - week
m - month
y - year
No String
type Combination type of multiple datapoints:
min - minimum value in timerange
max - maximum value in timerange (default)
avg - average value in timerange
No String
start_date Date of the first sample in ISO 8601 layout, if not set current day is used No String

Example Request

https://api.hub.embion.nl/v1/meter?id=[id]&uid=[uid]&period=q&range=d&type=max&start_date=2022-12-14
Response

Response body parameters The meter data is included in the JSON body of the response. The actual lay-out of the body varies depending on the query parameters given in the request. Data that is not used by the given meter is left out from the response body.

The following parameters can be present, if the data is available:

Response body parameters
VAR Description Units Format
timestamp Timestamp of the measurement ISO 8601 string
actpow Total active power 1 W Integer
apparpow Total apparent power 1 VA Integer
reactpow Total reactive power 1 VAR Integer
pf Total powerfactor 0.01 Integer
pfl1 Phase 1 powerfactor 0.01 Integer
pfl2 Phase 2 powerfactor 0.01 Integer
pfl3 Phase 3 powerfactor 0.01 Integer
actpowl1 Phase 1 active power 1 W Integer
actpowl2 Phase 2 active power 1 W Integer
actpowl3 Phase 3 active power 1 W Integer
il1 Phase 1 current 0.1 A Integer
il2 Phase 2 current 0.1 A Integer
il3 Phase 3 current 0.1 A Integer
vll12 Phase1-2 line-line voltage 0.1 V Integer
vll13 Phase1-3 line-line voltage 0.1 V Integer
vll23 Phase2-3 line-line voltage 0.1 V Integer
vl1 Phase1 to neutral voltage 0.1 V Integer
vl2 Phase2 to neutral voltage 0.1 V Integer
vl3 Phase3 to neutral voltage 0.1 V Integer
eimp imported energy counter 1 Wh Integer
eexp exported energy counter 1 Wh Integer
esolar used solar energy counter 1 Wh Integer
egrid used grid energy counter 1 Wh Integer
fgrid Measured grid frequency 0.01 Hz Integer
thdul1 Phase 1 voltage THD 0.01 % Integer
thdul2 Phase 2 voltage THD 0.01 % Integer
thdul3 Phase 3 voltage THD 0.01 % Integer
thdil1 Phase 1 current THD 0.01 % Integer
thdil2 Phase 2 current THD 0.01 % Integer
thdil3 Phase 3 current THD 0.01 % Integer
gas Used gas counter 0.01 m3 Integer
water Used water counter 0.01 m3 Integer
heat Used heat counter 100 J Integer
radi Measured radiation 0.1 W/m2 Integer
temp Measured temperature 0.1 C Integer
humi Measured humidity 0.01 % Integer
pres Measured pressure 1000 Pa Integer
flow Measured flow 0.01 liter/min Integer
weight Measured weight 1 gram Integer

Example response body

{
  [
    "timestamp": "2022-12-14T08:00:00.000Z",
    "actpow": 1000,
    "actpowl1": 100,
    "actpowl2": 1200,
    "actpowl3": -300,
    "apparpow": 1005,
    "eexp": 0,
    "egrid": 13541,
    "eimp": 36578912,
    "esolar": 31575661,
    "fgrid": 5011,
    "gas": 12300,
    "il1": 1000,
    "il2": 2000,
    "il3": 500,
    "pf": 30,
    "pfl1": 50,
    "pfl2": -50,
    "pfl3": 100,
    "reactpow": 100,
    "thdil1": 100,
    "thdil2": 200,
    "thdil3": 140,
    "thdul1": 111,
    "thdul2": 15,
    "thdul3": 109,
    "vl1": 23011,
    "vl2": 24011,
    "vl3": 23544,
    "vll12": 39821,
    "vll13": 40201,
    "vll23": 39098
  ],
  [
    "timestamp": "2022-12-14T08:15:00.000Z",
    "actpow": 1000,
    "actpowl1": 100,
    "actpowl2": 1200,
    "actpowl3": -300,
    "apparpow": 1005,
    "eexp": 0,
    "egrid": 13541,
    "eimp": 36578912,
    "esolar": 31575661,
    "fgrid": 5011,
    "gas": 15300,
    "il1": 1000,
    "il2": 2000,
    "il3": 500,
    "pf": 30,
    "pfl1": 50,
    "pfl2": -50,
    "pfl3": 100,
    "reactpow": 100,
    "thdil1": 100,
    "thdil2": 200,
    "thdil3": 140,
    "thdul1": 111,
    "thdul2": 15,
    "thdul3": 109,
    "vl1": 23011,
    "vl2": 24011,
    "vl3": 23544,
    "vll12": 39821,
    "vll13": 40201,
    "vll23": 39098
  ]
}

GET omvormergegevens

Method: GET | URL: https://api.hub.embion.nl/v1/inverter

This API endpoint returns individual inverter data.

Required permissions

Device tokens: (all allowed)
Third party tokens: monitoring

Request

Query parameters

Opmerking

Last value

Note that the last data sample is only available within the last two hours. If both the start date and period are not defined in the call, only the last data sample is returned if data is available; otherwise, no data will be returned.

Tip

Data time range

  • Users can optionally include a time with the start_date, which shifts the day interval. However, the total number of returned entries remains unchanged. If no time is specified, a day is considered from 00:00:00 to 23:59:59 in the selected timezone.
  • The start_date determines the beginning of the data range. The period defines the interval between returned dates, while the range specifies the end date/time relative to start_date, thereby determining the number of entries returned.
Opmerking

Period limitations

Please note there are some limitations when combining period and range

  • For period q (quarter-hourly) and h (hourly), the maximum range is d (one day).
  • For period d (daily), the maximum range is w (one week).
  • For period w (weekly), the maximum range is m (one month).
  • For period m (monthly), the maximum range is y (one year).
GET inverter data query parameters
VAR Description Mandatory Format
ID ID of the token (generated in the HUB) Yes String
uid the uid of the inverter to read, only one uid can be entered Yes String
period Select data return period:
l - last sample (default)
q - 15 minute
h - hourly
w - weekly
d - daily
m - monthly
y - yearly
No String
range Time range to show:
d - day (default)
w - week
m - month
y - year
No String
type Combination type of multiple datapoints:
min - minimum value in timerange
max - maximum value in timerange (default)
avg - average value in timerange
No String
start_date Date of the first sample in ISO 8601 layout, if not set current day is used No String

Example Request

https://api.hub.embion.nl/v1/inverter?id=[id]&uid=[uid]&period=h&range=d&type=max&start_date=2022-12-14GMT+0100
Response

Response body parameters The inverter data is included in the JSON body of the response. The actual lay-out of the body varies depending on the query parameters given in the request.

The body can contain the following parameters, if the data is available:

Response body parameters
VAR Description Units Format
timestamp Timestamp of the measurement ISO 8601 string
stat Inverter status Integer
kdy Inverter daily yield 1 Wh Integer
kty Inverter total yield 1 Wh Integer
pac Inverter AC power 1 W Integer
psol Inverter solar power 1 W Integer
ul1 Inverter phase 1 voltage 0.1 V Integer
ul2 Inverter phase 2 voltage 0.1 V Integer
ul3 Inverter phase 3 voltage 0.1 V Integer
il1 Inverter phase 1 current 0.1 A Integer
il2 Inverter phase 2 current 0.1 A Integer
il3 Inverter phase 3 current 0.1 A Integer
tmp1 Inverter internal temperature 1 0.1 C Integer
tmp2 Inverter internal temperature 2 0.1 C Integer
ilk Inverter leakage current or isolation resistance 0.0001 A Integer
arc Inverter arc detection status Integer
batpow Battery power (+charge, -discharge) 1 W Integer
batcap Remaining battery capacity 1 Wh Integer
batsoc Battery State Of Charge 0.1 % Integer
batsoh Battery State Of Health 0.1 % Integer
battemp Battery temperature 0.1 C Integer
string_data Individual string data (see table below) stringdata
Definition of stringdata
VAR Description Units Format
sid string number of inverter uid string
idc String current 0.1 A Integer
udc String voltage 0.1 V Integer
pdc String power 1 W Integer
ydc String daily yield 1 Wh Integer
sarc String arc detection status Integer

Example response body

{
  [
    "timestamp": "2022-12-13T23:00:00.000Z",
    "arc": 0,
    "batcap": 0,
    "batpow": 0,
    "batsoc": 0,
    "batsoh": 0,
    "battemp": 0,
    "il1": 56,
    "il2": 63,
    "il3": 77,
    "ilk": 3,
    "kdy": 1100000,
    "kty": 6100000,
    "pac": 10000,
    "psol": 20000,
    "string_data": [
      "sid": "1",
      "idc": 50,
      "udc": 5000,
      "pdc": 2500,
      "sarc": 0
    ],
    "stat": 1,
    "tmp1": 531,
    "tmp2": 366,
    "ul1": 2301,
    "ul2": 2405,
    "ul3": 2508
  ],
  [
    "timestamp": "2022-12-14T00:00:00.000Z",
    "arc": 0,
    "batcap": 0,
    "batpow": 0,
    "batsoc": 0,
    "batsoh": 0,
    "battemp": 0,
    "il1": 120,
    "il2": 130,
    "il3": 120,
    "ilk": 3,
    "kdy": 1200000,
    "pac": 14000,
    "string_data": [
      "sid": "1",
      "idc": 50,
      "udc": 5000,
      "pdc": 2500,
      "sarc": 0
    ],
    "stat": 1,
    "tmp1": 551,
    "tmp2": 346,
    "ul1": 2301,
    "ul2": 2405,
    "ul3": 2508
  ]
}

Installatieregeling

Introductie

De Plant Control API-eindpunten stellen gebruikers in staat om plant control-opdrachten te beheren en in te plannen voor hun EMS Controllers. Met deze plant control-opdrachten is het mogelijk om op afstand diverse processen van de verbonden apparaten te sturen, zoals het beperken van vermogensinvoer/-uitvoer, het sturen van het laden/ontladen van de batterij en het beheren van de werking van stuurbare belastingen.

Triggermethoden
Opmerking

Door de gebruiker gedefinieerde en op energieprijzen gebaseerde geplande opdrachten zijn alleen beschikbaar op Embion EMS Controllers met softwareversie 5.2.0 of hoger.

Er zijn drie verschillende triggermethoden voor plant control-opdrachten:

  1. Directe opdrachten (via de publieke API): Deze opdrachten worden verstuurd via het POST plant control command-eindpunt en worden direct op het apparaat uitgevoerd. Ze worden niet opgeslagen in het plant control-schema.
  2. Door de gebruiker geplande opdrachten (via de publieke API): Deze opdrachten worden ingepland voor een specifiek tijdstip in de toekomst en worden aangemaakt via het POST plant control schedule-eindpunt. Ze stellen gebruikers in staat acties te plannen en te automatiseren op basis van hun wensen. De bron is ingesteld op public_api in het plant control-schema.
  3. Op energieprijzen gebaseerde geplande opdrachten (automatisch gegenereerd): Deze opdrachten worden geactiveerd op basis van de plant control-regels en het prijsschema dat is ingesteld in de Energieprijzen-app van de HUB. Ze worden automatisch gegenereerd en toegevoegd aan het plant control-schema met energy_pricing als bron.
Activering en prioritering

Omdat er meerdere manieren zijn om plant control-opdrachten te activeren, is het belangrijk te begrijpen hoe deze opdrachten worden geactiveerd en geprioriteerd op het apparaat. De volgende regels zijn van toepassing:

Het onderstaande diagram toont de activering en prioritering van plant control-opdrachten op het apparaat:

Activeringsprioriteiten plant control
Activeringsprioriteiten plant control

GET installatieregeling

Methode: GET | URL: https://api.hub.embion.nl/v1/read_plantcontrol

Dit eindpunt geeft de momenteel actieve plant control-opdracht terug (als er één actief is op het apparaat).

Vereiste rechten

Apparaattokens: (alle toegestaan)
Tokens van derden: monitoring

Verzoek

Queryparameters

GET plant control queryparameters
VAR Beschrijving Verplicht
ID ID van het token (gegenereerd in de HUB) Ja

Voorbeeldverzoek

https://api.hub.embion.nl/v1/read_plantcontrol?id=[id]
Respons

Responsparameters

Let op: de velden dtcreated, dtupdated en valid_time zijn altijd aanwezig. Andere velden kunnen aanwezig zijn afhankelijk van de actieve stuuropdracht. Als er geen opdracht actief is, wordt de tekst "No plantcontrol command active" teruggegeven.

VAR Beschrijving Eenheden Formaat
dtcreated Tijdstip waarop de stuuropdracht is aangemaakt ISO 8601 String
dtupdated Tijdstip waarop de stuuropdracht is bijgewerkt ISO 8601 String
valid_time Tijd in seconden dat de stuuropdracht actief is Seconden Int
p_import_limit Netinvoerlimiet W Int
p_export_limit Netuitvoerlimiet W Int
rel_p_import_limit Relatieve netuitvoerlimiet W Int
rel_p_export_limit Relatieve netuitvoerlimiet W Int
control_generation Opwekkingssturing - String
control_consumption Verbruikssturing - String
control_pv_limit PV-limiet plant % Int
control_battery_setpoint Batterijsetpoint plant % Int
control_ev_limit EV-limiet plant % Int

Voorbeeldrespons

Een plant control-opdracht is actief:

{
  [
    "dtcreated": "2025-08-14T14:35:30.056Z",
    "dtupdated": "2025-08-14T14:35:30.056Z",
    "valid_time": 90,
    "p_export_limit": 100,
    "p_import_limit": 100,
    "control_ev_limit": 100,
    "control_pv_limit": 100,
    "control_generation": "min",
    "rel_p_export_limit": 100,
    "rel_p_import_limit": 100,
    "control_consumption": "nom",
    "control_battery_setpoint": 100
  ]
}

Geen opdracht actief:

{
  "No plantcontrol command active"
}

POST installatieregelingsbevel

Methode: POST | URL: https://api.hub.embion.nl/v1/plantcontrol

Met dit eindpunt kun je een plant control-opdracht naar het apparaat sturen om diverse aspecten van de plant aan te sturen. Dit omvat het aanpassen van invoer-/uitvoerlimieten, het sturen van opwekking en verbruik en het instellen van batterij- en EV-limieten.

Hoewel het mogelijk is alle parameters in één opdracht op te geven, wordt aanbevolen alleen de parameters op te nemen die gewijzigd moeten worden. Dit maakt de opdracht eenvoudiger en beter leesbaar. De Embion EMS Controller controleert ook of bepaalde limieten worden overschreden en past deze zo nodig aan.

Als een plant control-actie nog actief is wanneer een nieuwe opdracht wordt verstuurd, wordt de vorige opdracht overschreven of samengevoegd op basis van het verzoek, en wordt het antwoord dienovereenkomstig bijgewerkt.

Limieten

De volgende limieten gelden voor de parameters in een plant control-opdracht:

valid_time: Als weggelaten of ingesteld op 0, wordt de opdracht als oneindig beschouwd (geen vervaltijd). Als opgegeven en niet nul, moet de waarde minimaal 90 (seconden) zijn. Waarden kleiner dan 90 worden afgewezen met de fout valid_time_too_short.

Opdrachten zonder acties (geen limieten of control_*-velden): Mogen alleen worden verstuurd als een eindige valid_time expliciet is opgegeven (d.w.z. valid_time aanwezig en groter dan of gelijk aan 90). Dit voorkomt het versturen van lege, niet-verlopende opdrachten.

Algemene opmerkingen: Verstuur bij voorkeur alleen de parameters die je wilt wijzigen. Wanneer merge is ingesteld op true, worden nieuwe waarden samengevoegd met bestaande actieve opdrachten; anders worden ze overschreven. De laatste valid_time van samengevoegde opdrachten wordt gebruikt.

Vereiste rechten

Apparaattokens: Control access Tokens van derden: control

Verzoek

Bodyparameters

Opmerking

Sommige parameters zijn pas beschikbaar vanaf specifieke softwareversies. Deze parameters zijn gemarkeerd met een versietag (bijv. [^4.2.0]). Dit voorbeeld geeft aan dat de parameter beschikbaar is vanaf versie 4.2.0. Zorg ervoor dat je apparaat de vereiste softwareversie heeft om deze parameters te kunnen gebruiken.

Opmerking

Conflicterende setpoints Als conflicterende setpoints worden opgegeven, heeft het setpoint dat resulteert in het laagste vermogensuitvoer voorrang.

Waarschuwing

Opdrachten samenvoegen Als merge niet wordt gebruikt, overschrijven nieuwe opdrachten de vorige opdrachten. Als merge wordt gebruikt, worden eerder ingestelde limieten samengevoegd met de nieuwe opdracht. De meest recentelijk opgegeven valid_time wordt toegepast (oneindig als de waarde 0 is of de variabele valid_time niet is opgegeven).

POST plant control command bodyparameters
VAR Beschrijving Verplicht Formaat Eenheid
id ID van het token Ja String
p_import_limit Netinvoerlimiet Nee Integer W
p_export_limit Netuitvoerlimiet Nee Integer W
rel_p_import_limit [^4.2.0] Relatieve netinvoerlimiet Nee Integer %
rel_p_export_limit [^4.2.0] Relatieve netuitvoerlimiet Nee Integer %
control_generation - min minimaliseer opwekking
- max maximaliseer opwekking
- nom nominale opwekking
Nee String
control_consumption - min minimaliseer verbruik
- max maximaliseer verbruik
- nom nominaal verbruik
Nee String
control_pv_limit [^4.2.0] PV-limiet plant Nee Integer %
control_battery_setpoint (+laden, -ontladen) [^4.2.0] Batterijsetpoint plant Nee Integer %
control_ev_limit [^4.2.0] EV-limiet plant Nee Integer %
min_bess_soc [^5.2.0] Minimale BESS SoC Nee Integer %
max_bess_soc [^5.2.0] Maximale BESS SoC Nee Integer %
des_bess_soc [^5.2.0] Gewenste BESS SoC Nee Integer %
valid_time Tijd in seconden dat de gegeven opdracht actief blijft op de Embion EMS (moet gelijk aan of groter dan 90 zijn).
Oneindig als de waarde 0 is of de variabele niet is opgegeven.
Nee Integer sec.
merge Als true en een huidige plant control-opdracht actief is, wordt deze samengevoegd met de gegeven opdracht.
Standaard is false.
Nee Boolean

De items control_generation en control_consumption kunnen worden gebruikt om de opwekking en het verbruik van de plant onafhankelijk van de plantconfiguratie te sturen.

Plant control-acties
VAR Waarde Beschrijving
control_generation min Vermindert de opwekking tot het minimum, waardoor PV-omvormers worden uitgeschakeld en windturbines stoppen.
control_generation nom Laat opwekking door zon en wind normaal functioneren.
control_generation max Maakt ook het starten van eventuele extra generatoren mogelijk (indien aanwezig in de plant).
control_consumption min Vermindert stuurbare belastingen zoals warmtepompen en EV-laders tot minimaal verbruik.
control_consumption nom Laat normale stuurbare belastingen werken binnen de plantlimieten.
control_consumption max Verhoogt het vermogen voor stuurbare belastingen tot het maximum. EV-laders verhogen het laadvermogen tot het maximum (binnen de plantlimieten) en warmtepompen verhogen of verlagen het setpoint om het stroomverbruik te verhogen.

Voorbeeldverzoek

https://api.hub.embion.nl/v1/plantcontrol
{
  [
    "id": "119mt001pj51d",
    "p_export_limit": 20000,
    "p_import_limit": 50000,
    "control_generation": "max",
    "control_consumption": "nom",
    "valid_time": 200
  ]
}
Respons

De responsinhoud bevat informatie over of de opdracht succesvol is verstuurd.

Responsparameters

Responsparameters
VAR Beschrijving Formaat Optioneel
success Of de opdracht is verstuurd (true = verstuurd) boolean Nee
value Optioneel beschrijvend bericht string Ja

Het veld value verschijnt als de opdracht niet kon worden verstuurd of als een bestaande opdracht werd overschreven. Het veld kan de volgende waarden hebben:

Plant control-waarden
VAR Beschrijving
unsupported De plant control-functie wordt niet ondersteund op het apparaat
disabled De plant control-functie is actief uitgeschakeld door het apparaat
valid_time_too_short Het veld valid_time moet gelijk aan of groter dan 90 zijn; anders wordt deze fout weergegeven
offline Het apparaat is offline (geen data of status ontvangen in de laatste 2 minuten)
overwritten De vorige opdracht wordt overschreven
merged De vorige opdracht is samengevoegd met de opgegeven opdracht
Hub command is currently active Een plant control-opdracht van de HUB-interface (zoals een statuscontrole van een asset) is momenteel actief. Wacht tot de HUB-opdracht is voltooid voordat je een nieuwe opdracht via de API verstuurt.

Voorbeeldrespons

Plant control-opdracht succesvol verstuurd

{
  [
    "success": true
  ]
}

Plant control-opdracht kon niet worden verstuurd (plant is offline)

{
  [
      "success": false,
      "value": "offline"
  ]
}

Plant control-opdracht kon niet worden verstuurd (HUB-opdracht is actief)

{
  [
      "success": false,
      "value": "Hub command is currently active"
  ]
}

GET installatieregeling-planning

Methode: GET | URL: https://api.hub.embion.nl/v1/plantcontrol/schedule

Dit eindpunt geeft alle plant control-opdrachten terug die zijn ingepland voor het opgegeven apparaat.

Vereiste rechten

Apparaattokens: (alle toegestaan) Tokens van derden: monitoring

Verzoek

Queryparameters

GET plant control schedule verzoekqueryparameters
VAR Beschrijving Verplicht
id ID van het token (gegenereerd in de HUB) Ja
dtstart Startdatum en -tijd van het schema (ISO 8601-formaat) Nee
dtend Einddatum en -tijd van het schema (ISO 8601-formaat) Nee
source Bron van het schema (bijv. public_api, energy_pricing) Nee
command_name Naam van de plant control-opdrachtactie (bijv. control_generation, p_export_limit) Nee

Voorbeeldverzoek

https://api.hub.embion.nl/v1/plantcontrol/schedule?id=[id]
Respons

De responsinhoud bevat het plant control-schema in JSON-formaat. De inhoud bevat de volgende parameters:

Responsparameters
VAR Beschrijving Formaat
id ID van de opdracht string
deviceid ID van het apparaat string
command_name Naam van de opdrachtactie (zie de requestbody van POST Plant control) string
command_value Waarde gekoppeld aan de opdrachtactie (zie de requestbody van POST Plant control) string
dtstart Startdatum en -tijd van de opdracht (ISO 8601-formaat) string
dtend Einddatum en -tijd van de opdracht (ISO 8601-formaat) string
source Bron van de opdracht (bijv. public_api, energy_pricing) string

Voorbeeldrespons

{ 
  [
    "id": "1r0ac125uj51d",
    "deviceid": "1quxh001ob51d",
    "command_name": "p_import_limit",
    "command_value": "1000",
    "dtstart": "2025-09-04T06:00:00.000Z",
    "dtend": "2025-09-04T06:15:00.000Z",
    "source": "energy_pricing"
  ],
  [
    "id": "1r0ac126uj50d",
    "deviceid": "1quxh001ob51d",
    "command_name": "p_import_limit",
    "command_value": "1000",
    "dtstart": "2025-09-04T06:15:00.000Z",
    "dtend": "2025-09-04T06:30:00.000Z",
    "source": "energy_pricing"
  ],
  [
    "id": "1r0ac127uj51d",
    "deviceid": "1quxh001ob51d",
    "command_name": "p_import_limit",
    "command_value": "1000",
    "dtstart": "2025-09-04T06:30:00.000Z",
    "dtend": "2025-09-04T06:45:00.000Z",
    "source": "energy_pricing"
  ],
  [
    "id": "1r0ac128uj50d",
    "deviceid": "1quxh001ob51d",
    "command_name": "p_import_limit",
    "command_value": "1000",
    "dtstart": "2025-09-04T06:45:00.000Z",
    "dtend": "2025-09-04T07:00:00.000Z",
    "source": "energy_pricing"
  ]
}

POST installatieregeling-planning

Methode: POST | URL: https://api.hub.embion.nl/v1/plantcontrol/schedule

Met dit eindpunt kun je nieuwe plant control-schema-items aanmaken voor een apparaat, zodat je kunt plannen wanneer specifieke plant control-opdrachten worden uitgevoerd.

Limieten

Er geldt een maximumlimiet van 500 schema-items per opdrachtactie (control_generation, p_import_limit, etc.) per apparaat. Als je meer dan deze limiet probeert toe te voegen, geeft de API een respons terug met statuscode 200 OK en de volgende inhoud:

{
  [
    "success": false,
    "value": "Schedule item limit exceeded for p_import_limit: would have 501 items (limit: 500)"
  ]
}

Schema-items met dezelfde command_name die overlappende tijdsperioden hebben (d.w.z. hun dtstart en dtend overlappen) worden als conflicterend beschouwd en de API wijst het verzoek af met een responsinhoud zoals deze:

{
  [
    "success": false,
    "value": "Plant control commands collide with existing commands"
  ]
}
Vereiste rechten

Apparaattokens: Control access Tokens van derden: Control

Verzoek

De requestbody moet een JSON-array zijn met één of meer opdrachtobjecten. Elk opdrachtobject moet de volgende parameters bevatten:

Bodyparameters
VAR Beschrijving Formaat Verplicht
dtstart Startdatum en -tijd van de opdracht (ISO 8601-formaat) string Ja
dtend Einddatum en -tijd van de opdracht (ISO 8601-formaat) (opdracht blijft actief als niet opgegeven) string Nee
command_name Naam van de opdrachtactie die moet worden uitgevoerd string Ja
command_value Waarde gekoppeld aan de opdrachtactie string of integer Ja
overwrite_existing Overschrijft bestaande plant control-schema’s die anders een conflict zouden veroorzaken bool Ja
Opmerking

Zonder de queryparameter overwrite_existing worden verzoeken met schema-items die conflicten zouden veroorzaken (via de publieke API ingediend met dezelfde opdrachtactie en overlappende start- en eindtijden) geweigerd. Er worden dan geen nieuwe schema-items toegevoegd.

Voorbeeldverzoekbody
{
  [
    "dtstart": "2025-08-25T17:00:00Z",
    "dtend": null,
    "command_name": "control_generation",
    "command_value": "max"
  ],
  [
    "dtstart": "2025-08-26T17:00:00Z",
    "dtend": "2025-08-28T17:00:00Z",
    "command_name": "control_consumption",
    "command_value": "max"
  ],
  [
    "dtstart": "2025-08-26T11:00:00Z",
    "dtend": "2025-08-28T16:00:00Z",
    "command_name": "p_export_limit",
    "command_value": 0
  ]
}
Respons

De responsinhoud bevat de volgende parameters:

Responsparameters
VAR Beschrijving Formaat
success Of de schema-items succesvol zijn opgeslagen (true = opgeslagen) boolean
value Optioneel beschrijvend bericht string
Voorbeeldrespons

Plant control-schema succesvol verstuurd:

{
  [
    "success": true,
    "value": "Plant control schedule items inserted successfully"
  ]
}

Plant control-schema kon niet worden verstuurd (door conflicten met bestaande opdrachten):

{
  [
    "success": false,
    "value": "Plant control commands collide with existing commands"
  ]
}

Plant control-schema kon niet worden verstuurd (door overschrijding van de schema-itemlimiet):

{
  [
    "success": false,
    "value": "Schedule item limit exceeded for control_generation: would have 501 items (limit: 500)"
  ]
}

DELETE installatieregeling-planning

Methode: DELETE | URL: https://api.hub.embion.nl/v1/plantcontrol/schedule

Met dit eindpunt kun je bestaande plant control-schema-items verwijderen voor een apparaat. Alleen schema-items die via de publieke API zijn aangemaakt, kunnen met dit eindpunt worden verwijderd. Schema-items gegenereerd door andere bronnen (bijv. energieprijzen) kunnen niet worden verwijderd.

Het is mogelijk om alle schema-items voor een apparaat te verwijderen, of alleen de schema-items met een specifieke opdrachtactienaam. Dit kan worden gedaan door de bijbehorende queryparameter command_name op te geven.

Vereiste rechten

Apparaattokens: Control access Tokens van derden: Control

Verzoek

Queryparameters

DELETE plant control schedule verzoekqueryparameters
VAR Beschrijving Verplicht
id ID van het token (gegenereerd in de HUB) Ja
command_name Naam van de opdrachtactie (verwijdert alle schema-items met deze opdrachtactienaam als opgegeven) Nee
Voorbeeldverzoek
https://api.hub.embion.nl/v1/plantcontrol/schedule?id=[id]
Respons

De responsinhoud bevat de volgende parameters:

Responsparameters
VAR Beschrijving Formaat
success Of het schema-item succesvol is verwijderd (true = verwijderd) boolean
value Optioneel beschrijvend bericht string
Voorbeeldrespons
{
  [
    "success": true,
    "value": "All scheduled plant control commands removed successfully"
  ]
}

DELETE plant control schedule item op ID

Methode: DELETE | URL: https://api.hub.embion.nl/v1/plantcontrol/schedule/<schedule_item_id>

Met dit eindpunt kun je een specifiek plant control-schema-item verwijderen op basis van het ID. Alleen schema-items die via de publieke API zijn aangemaakt, kunnen met dit eindpunt worden verwijderd. Schema-items gegenereerd door andere bronnen (bijv. energieprijzen) kunnen niet worden verwijderd.

Vereiste rechten

Apparaattokens: Control access Tokens van derden: Control

Verzoek

URL-parameters

DELETE plant control schedule verzoek-URL-parameters
VAR Beschrijving Verplicht
schedule_item_id ID van het te verwijderen plant control-schema-item Ja

Queryparameters

DELETE plant control schedule op ID verzoekqueryparameters
VAR Beschrijving Verplicht
id ID van het token (gegenereerd in de HUB) Ja
Voorbeeldverzoek
https://api.hub.embion.nl/v1/plantcontrol/schedule/?id=[id]
Respons

De responsinhoud bevat de volgende parameters:

Responsparameters
VAR Beschrijving Formaat
success Of het schema-item succesvol is verwijderd (true = verwijderd) boolean
value Optioneel beschrijvend bericht string
Voorbeeldrespons
{
  [
    "success": true,
    "value": "Plant control schedule item removed successfully"
  ]
}

Informatie voor derden

GET verbonden apparaten

Methode: GET | URL: https://api.hub.embion.nl/v1/logged-in-third-party/devices

Dit eindpunt geeft alle apparaten terug die verbonden zijn met de ingelogde derde partij. Het is daarom alleen toegankelijk met een token van een derde partij. De respons bevat een combinatie van het serienummer van het apparaat en een ID voor gebruik in API-aanroepen die betrekking hebben op dat apparaat.

Vereiste rechten

Tokens van derden: Monitoring

Verzoek

Queryparameters

Queryparameters
VAR Beschrijving Verplicht
ID ID van het token van de derde partij Ja
Voorbeeldverzoek
https://api.hub.embion.nl/v1/logged-in-third-party/devices?id=[id]
Respons

De responsinhoud is een JSON-array van objecten, elk met een verbonden apparaat.

Responsparameters
VAR Beschrijving Formaat
id ID van het apparaat (voor gebruik in andere API-aanroepen) string
serial_number Serienummer van het apparaat string
Voorbeeldrespons
{
  [
    "id": "1q6dz002pp50d",
    "serial_number": "05002516010026"
  ],
  [
    "id": "1qayl002cf50d",
    "serial_number": "05002516010029"
  ],
  [
        "id": "1qbu3002bs50d",
        "serial_number": "01002309010028"
  ]
}

GET verbonden apparaat op serienummer

Method: GET | URL: https://api.hub.embion.nl/v1/logged-in-third-party/devices/[serial number]

This endpoint returns information of a device that corresponds to the given serial number if it is connected to the logged in third party. This endpoint is only accessible with a third party token. The response contains a combination of the device serial number and an ID to use in API calls related to that device.

Required permissions

Third party tokens: Monitoring

Request

URL parameters

URL parameters
VAR Description Mandatory
serial_number Serial number of the device Yes

Query parameters

Query parameters
VAR Description Mandatory
ID ID of the third party token Yes
Example request
https://api.hub.embion.nl/v1/logged-in-third-party/devices/?id=[id]
Response
Response body parameters
VAR Description Format
ID ID of the device (for use in other API calls) string
serial_number Serial number of the device string
Example response body
{
  [
    "id": "1qayl002cf50d",
    "serial_number": "05002516010029"
  ]
}