Application API

De GridSense Application API geeft externe applicaties alleen-lezen-toegang tot installatiegegevens en de laatst bekende toestand van omvormers, batterijen, energiemeters, laadpalen, relais en boilers, plus de actuele geaggregeerde energiestroom.

Basis-URL: https://api.gridsense.nl/application/v1.

De API uitproberen

1. Open Installaties opvragen.
2. Open Authenticatie in het API-testpaneel, selecteer ApiKey en plak de volledige gsak_…-API-sleutel van je applicatie. Voeg geen Bearer toe.
3. Klik op Versturen. Het API-testpaneel toont de echte HTTP-status en het JSON-antwoord van de API. De voorbeeldantwoorden elders op de pagina zijn fictief.
4. Kopieer een id uit de ontvangen array installations en open Installatieapparaten opvragen.
5. Vervang het voorbeeld bij installationId door dat ID en verstuur het verzoek om de laatst gemelde apparaattoestand van de installatie te zien.
6. Open Actuele energiestroom opvragen met hetzelfde installationId voor een overzicht van online apparaten. gridPower is positief bij afname en negatief bij teruglevering; data kan null zijn.

Het API-testpaneel bewaart de sleutel in de lokale opslag van deze browser, ook bij het wisselen van endpointpagina of taal en na het herladen van de pagina. Klik op API-sleutel en antwoord wissen als je klaar bent om opgeslagen inloggegevens en het huidige resultaat te verwijderen. Verzoeken gaan via de GridSense-documentatieserver, omdat de Application API geen browserverzoeken vanaf andere domeinen toestaat. De documentatieproxy stuurt je authenticatie door naar de API en slaat antwoorden niet op in een cache.

Authenticatie en toegang

Gebruik Api-Key: YOUR_API_KEY of Authorization: Bearer YOUR_API_KEY. Het API-testpaneel ondersteunt ook BearerAuth: plak dezelfde volledige sleutel zonder voorvoegsel; Bearer wordt automatisch toegevoegd. Stuur één authenticatieheader tegelijk. Als beide headers aanwezig zijn, heeft een Bearer-Authorization-header voorrang.

Een applicatie heeft een expliciete toewijzing voor een installatie nodig en de eigenaar moet nog steeds toegang tot die installatie hebben. Een applicatie van een gebruiker krijgt toegang via de directe installatietoegang van de eigenaar; alleen lidmaatschap van een bedrijf is niet voldoende. Een applicatie van een bedrijf kan toegewezen installaties van dat bedrijf uitlezen. De toegang wordt bij elk verzoek gecontroleerd.

Ontbrekende, verkeerd gevormde, onbekende, ingetrokken of verlopen sleutels en uitgeschakelde applicaties krijgen allemaal 401 UNAUTHORIZED. Sleutels worden alleen bij het aanmaken eenmalig getoond. Vervang een sleutel door een nieuwe aan te maken, je integratie bij te werken en daarna de oude sleutel in te trekken.

Aanroepen vanuit je integratie

Bewaar de sleutel in de omgevingsvariabelen of geheimenopslag van je server. Bijvoorbeeld, nadat je GRIDSENSE_API_KEY hebt ingesteld:

curl --fail-with-body \
  -H "Api-Key: $GRIDSENSE_API_KEY" \
  'https://api.gridsense.nl/application/v1/getInstallations'

# Vervang 42 door een installatie-ID uit getInstallations.
curl --fail-with-body \
  -H "Authorization: Bearer $GRIDSENSE_API_KEY" \
  'https://api.gridsense.nl/application/v1/getInstallationDevices?installationId=42'

curl --fail-with-body \
  -H "Api-Key: $GRIDSENSE_API_KEY" \
  'https://api.gridsense.nl/application/v1/getInstallationCurrentEnergyFlow?installationId=42'

Deze documentatie beschrijft GET-verzoeken met queryparameters. De API accepteert ook parameters in de formulierinhoud van een POST-verzoek. POST-waarden hebben voorrang op querywaarden. Alle drie endpoints lezen alleen gegevens.

Antwoorden en fouten

Geslaagde antwoorden bevatten valid: true. Fouten bevatten valid: false en een machineleesbare error. Controleer zowel de HTTP-status als de JSON-inhoud.

Het API-testpaneel in de documentatie kan daarnaast 502 of 504 teruggeven als de API onbereikbaar is, een time-out optreedt, een omleiding volgt of het antwoord geen JSON is. Dit zijn fouten van de documentatieproxy, geen foutcodes van de Application API.

Apparaatarrays kunnen leeg zijn. Metingen met null zijn onbekend, niet beschikbaar of niet ondersteund, niet nul. Ook offline apparaten worden opgenomen; controleer dus lastSeenDate voordat je een waarde als actueel beschouwt. Apparaten kunnen verschillende bijwerktijden hebben. Lees Vermogensrichting en antwoordvelden voordat je energiestromen berekent.

OpenAPI-specificatie

Download de Nederlandstalige OpenAPI 3.1-specificatie voor je API-client of codegenerator. De endpointdocumentatie beschrijft onder Antwoordinhoud voor elk veld de betekenis, het type en of null is toegestaan. De Engelstalige specificatie beschrijft hetzelfde API-contract. Veldnamen, enumwaarden en voorbeeldgegevens zijn in beide talen gelijk.

De Application API geeft geen gebruikers, bedrijfsobjecten, facturen, abonnementen, gatewayobjecten, MQTT-inloggegevens, ruwe fabrikantgegevens, regelschema's of voertuigen terug. Velden zoals apparaatmodus en gewenste relaistoestand zijn alleen-lezen-waarnemingen. Applicatiebeheer en apparaatbesturing gebruiken aparte API's en vallen buiten deze documentatie.