API · versie 1

Externe API

Haal marktprijzen, het leveranciersoverzicht en, met een eigen sleutel, de gegevens van één dossier programmatisch op. Dezelfde berekeningen als de website.

Bereikbaarheid. De API is voorlopig enkel bereikbaar binnen het Tailscale-netwerk van SEF (basis-URL hieronder, poort 8443). Op een echte server volgt een openbaar adres; het pad /api/v1 en het contract blijven dan gelijk. Een sleutel vraag je via contact.

Snelstart

export SEF_URL="https://energie-vlaanderen.tamarin-newton.ts.net:8443"
export SEF_SLEUTEL="sef_..."

curl -s -H "Authorization: Bearer $SEF_SLEUTEL" "$SEF_URL/api/v1/status"
curl -s -H "Authorization: Bearer $SEF_SLEUTEL" \
     "$SEF_URL/api/v1/leveranciers/overzicht?energie=Elektriciteit"

Het volledige contract (parameters en antwoorden) staat in openapi-extern.json (OpenAPI 3).

Authenticatie en scopes

Elke aanvraag draagt Authorization: Bearer <sleutel>. Een sleutel begint met sef_ en hoort bij één account en één dossier. Hij is standaard 365 dagen geldig, kan elk moment worden ingetrokken en werkt niet meer zodra het account de toegang tot het dossier verliest. Behandel hem als een wachtwoord: niet in code, URL's of logs.

Scope	Geeft toegang tot
`publiek`	Publieke marktdata: prijzen, leveranciersoverzicht, netbeheerders, nieuws, status. Geen persoonsgegevens.
`dossier:lezen`	Het dossier van de sleutel lezen: aansluitingen, verbruik, contractperiodes, simulaties, vergelijkingen.
`dossier:uitvoeren`	Een simulatie of contractvergelijking starten op dat dossier.

Endpoints

Alle paden staan onder /api/v1. Wat hier niet staat (aanmelden, accountbeheer, uploaden, wissen, facturen) bestaat extern niet.

Methode	Pad	Scope	Wat
`GET`	`/api/v1/status`	`publiek`	Grove status voor de publieke statuspagina: geen fouttekst, geen host.
`GET`	`/api/v1/nieuws`	`publiek`	Goedgekeurd energienieuws, nieuwste eerst (ADR-0032). Enkel titel,
`GET`	`/api/v1/tariefsignalen`	`publiek`	Tariefsignalen bij één resultaat (ADR-0033): `geldt` = een aangekondigde
`GET`	`/api/v1/prijzen/indexen`	`publiek`	Alle marktindexreeksen met gerealiseerde maandwaarden, meest gebruikte eerst.
`GET`	`/api/v1/prijzen/index`	`publiek`	Maandwaarden (€/MWh, gerealiseerd) van één reeks. Onbekende reeks -> 404.
`GET`	`/api/v1/prijzen/verloop`	`publiek`	Gemiddelde zuivere energieprijs per maand (c€/kWh, excl. btw) van het
`GET`	`/api/v1/leveranciers/overzicht`	`publiek`	Bewaarde rangschikking van de laatste nachtelijke run op het
`GET`	`/api/v1/netbeheerders/vergelijking`	`publiek`	Jaarlijkse meerkost per netbeheerder t.o.v. de goedkoopste, per
`GET`	`/api/v1/mij/aansluitingen`	`dossier:lezen`	Aansluitingen van de gebruiker, met EAN-masker en meetbereik.
`GET`	`/api/v1/mij/verbruik`	`dossier:lezen`	Afname en injectie per maand of dag, lokale tijd, half-open [van, tot).
`GET`	`/api/v1/mij/contractperiodes`	`dossier:lezen`	Alle contractperiodes, met de prijs van elke afgesloten periode
`GET`	`/api/v1/mij/prijs`	`dossier:lezen`	All-in prijs per kWh (EUR incl. btw) van het huidige
`GET`	`/api/v1/mij/simulatie-opties`	`dossier:lezen`	Keuzes voor het simulatieformulier: batterijmodellen (Marstek-lijn
`GET`	`/api/v1/mij/simulaties`	`dossier:lezen`	Bewaarde simulaties van de gebruiker, nieuwste eerst (ADR-0044).
`POST`	`/api/v1/mij/simulaties`	`dossier:uitvoeren`	Simuleert batterij, extra panelen, een elektrische wagen en/of een
`GET`	`/api/v1/mij/simulaties/{run_id}`	`dossier:lezen`	Eén eigen simulatie met haar samenvatting (null bij simulaties van vóór
`GET`	`/api/v1/mij/vergelijkingen`	`dossier:lezen`	De laatste contractvergelijkingen van de gebruiker, nieuwste eerst.
`POST`	`/api/v1/mij/vergelijkingen`	`dossier:uitvoeren`	Zet een contractvergelijking op de eigen meetdata in de wachtrij.
`GET`	`/api/v1/mij/vergelijkingen/{opdracht_id}`	`dossier:lezen`	Status van één eigen vergelijking; als ze klaar is ook de rangschikking.
`POST`	`/api/v1/mij/aansluitingen/{aansluiting_id}/meetwaarden`	`dossier:schrijven`	Kwartierwaarden uit een P1-poort (Home Assistant) op een bestaande

Conventies

Bedragen en energie zijn decimale strings ("0.12345"), nooit floats. Rond af bij het tonen, niet eerder.
Datums zijn ISO 8601. Verbruik is in lokale tijd (Europe/Brussels) over half-open perioden [van, tot); een dag heeft 92, 96 of 100 kwartieren.
Verbruik is begrensd: per maand hoogstens 5 jaar, per dag hoogstens 366 dagen. EAN-nummers komen enkel gemaskeerd terug.
Elk antwoord heeft X-Correlation-ID; geef die door bij een vraag over een aanvraag.
Versie 1 krijgt enkel uitbreidingen (nieuwe routes, optionele parameters, extra velden): negeer velden die je niet kent. Een brekende wijziging komt als /api/v2 naast v1.

Fouten

Fouten zijn application/problem+json met een stabiele code en een correlation_id.

Status	Code	Betekenis
401	`NIET_GEMACHTIGD`	Sleutel ontbreekt, is ongeldig, verlopen of ingetrokken.
403	`SCOPE_ONVOLDOENDE`	De sleutel mist de vereiste scope.
404	`NIET_GEVONDEN`	Onbekende route, onbekend object of geen toegang tot het dossier.
422	`INVOER_ONGELDIG e.a.`	Ongeldige parameters; de code zegt welke.
429	`TE_VEEL_AANVRAGEN`	Meer dan 60 aanvragen per minuut met deze sleutel, of meer dan 2 POST-aanvragen (simulatie of vergelijking starten) per minuut; wacht de seconden uit Retry-After.
429	`SIMULATIE_BEZIG, TE_VEEL_OPDRACHTEN, WACHTRIJ_VOL`	Een berekening loopt al of de wachtrij is vol; probeer later opnieuw.

Probeer een 401, 403, 404 of 422 niet automatisch opnieuw; een 429 wel, na Retry-After.

Een contractvergelijking starten

Een vergelijking loopt asynchroon (seconden tot een minuut). Per dossier loopt hoogstens één opdracht tegelijk: een tweede POST geeft de lopende terug (nieuw: false).

# 1. starten: 202 met het opdracht-id
curl -s -X POST -H "Authorization: Bearer $SEF_SLEUTEL" -H "Content-Type: application/json" \
     -d '{"energie": "elektriciteit"}' "$SEF_URL/api/v1/mij/vergelijkingen"

# 2. status opvragen tot "klaar" of "fout" (wachtend, bezig, klaar, fout)
curl -s -H "Authorization: Bearer $SEF_SLEUTEL" "$SEF_URL/api/v1/mij/vergelijkingen/<id>"

Peil niet vaker dan om de paar seconden.