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:
| 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.
| 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 |
Belangrijke opmerkingen:
|
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:
| 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
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
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
| 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
| 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:
| 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
| 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
| 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
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. |
Datatijdsbereik
|
Periodebeperkingen Houd er rekening mee dat er beperkingen zijn bij het combineren van periode en bereik
|
| 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:
| 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
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. |
Data time range
|
Period limitations Please note there are some limitations when combining period and range
|
| 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:
| 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
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. |
Data time range
|
Period limitations Please note there are some limitations when combining period and range
|
| 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:
| 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 |
| 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
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:
- 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.
- 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_apiin het plant control-schema. - 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_pricingals 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:
- Directe opdrachten worden altijd direct uitgevoerd en hebben voorrang op geplande opdrachten. Ze overschrijven actieve geplande opdrachten. Als de parameter
mergeis ingesteld optruebij het versturen van een directe opdracht, wordt de opdracht samengevoegd met actieve geplande opdrachten in plaats van ze te overschrijven. - Geplande opdrachten bevatten één plant control-actie (in tegenstelling tot directe opdrachten) en worden geactiveerd op basis van de ingestelde start- (
dtstart) en eindtijd (dtend). Als meerdere geplande opdrachten tegelijkertijd actief zijn, wordt de opdracht met de hoogste prioriteit uitgevoerd. De prioriteit wordt bepaald door de bron van de opdracht: door de gebruiker geplande opdrachten (public_api) hebben een hogere prioriteit dan op energieprijzen gebaseerde opdrachten (energy_pricing). Schema-items met verschillende opdrachten (bijv.control_generationenp_export_limit) kunnen tegelijkertijd actief zijn, omdat ze verschillende aspecten van de plant aansturen.
Het onderstaande diagram toont de activering en prioritering van plant control-opdrachten op het apparaat:
![]() |
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
| 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
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. |
Conflicterende setpoints Als conflicterende setpoints worden opgegeven, heeft het setpoint dat resulteert in het laagste vermogensuitvoer voorrang. |
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). |
| 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.
| 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
| 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:
| 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
| 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:
| 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:
| 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 |
Zonder de queryparameter |
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:
| 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
| 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:
| 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
| VAR | Beschrijving | Verplicht |
|---|---|---|
| schedule_item_id | ID van het te verwijderen plant control-schema-item | Ja |
Queryparameters
| 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:
| 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
| 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.
| 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
| VAR | Description | Mandatory |
|---|---|---|
| serial_number | Serial number of the device | Yes |
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
| 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"
]
}
