Laadpunten API (DOT-NL)
Warning
Deze API's zijn nog in ontwikkeling en de specificaties kunnen nog wijzigen.
DOT-NL (Dataplatform Openbare Toegankelijke laadpunten Nederland) is het portaal dat realtime data over alternatieve energie infrastructuur voor voertuigen ontvangt van leveranciers en beschikbaar stelt.
Aansluiten
Om aan te sluiten op DOT-NL kan contact worden opgenomen met de NDW Servicedesk. Geef hierbij aan dat het gaat om het aansluiten op DOT-NL of NAP-EV. Vervolgens zal er afgestemd worden hoe de verbinding wordt opgezet en zullen er aansluittesten uitgevoerd worden.
Tijdigheid
De aangeleverde data dient actueel te zijn. Dit wil zeggen dat wijzigingen binnen 1 minuut aangeleverd dienen te worden.
Aanleveren met OCPI-2.2.1
OCPI (Open Charge Point Interface) is een protocol dat communicatie tussen laadpuntoperators en dienstverleners mogelijk maakt en wordt onderhouden door de EVRoaming Foundation.
Voor levering aan DOT-NL, middels OCPI-2.2.1, zijn openapi-specificaties opgesteld voor de pull- en de push-functionaliteit (4.1.3 in OCPI-2.2.1), die aangeven welke informatie verwacht wordt middels welke endpoints.
Als aanvulling op OCPI-2.2.1 zijn, vanwege de AFIR, de volgende optionele elementen verplicht gemaakt in de openapi-specificaties:
| Object | Element |
|---|---|
| Location | opening_times |
| Location | energy_mix |
| EVSE | parking_restrictions |
| Connector | max_electric_power |
| Connector | tariff_ids |
Pull
Om de volledige set van objecten en de laatste stand van individuele objecten te weten, worden deze periodiek (dagelijks) opgehaald middels de pull-functionaliteit. Hiervoor dient een server beschikbaar te zijn die conform de pull-API openapi-spec de huidige toestand levert als response op een GET.
Pull - Locaties
Voor het aanleveren van de Locations dient een endpoint beschikbaar te zijn die luistert naar verzoeken voor zowel de volledige set, als ook specifieke locaties. Het ophalen van individuele EVSE- en Connector-objecten wordt vooralsnog niet gebruikt.
Pull - Tarieven
Voor het aanleveren van de Tariffs dient een endpoint beschikbaar te zijn die luisterd naar verzoeken voor de volledige set van tarieven.
Pull - Authenticatie
Warning
De credentials module van OCPI wordt niet gebruikt.
Voor het ophalen van de huidige toestand bij de leverancier dienen de authenticatie gegevens beschikbaar te worden gesteld. Het is mogelijk om op 2 manieren toegagng te verlenen, namelijk middels een token/api-key of middels OAuth2.
Bij gebruik van een afgesproken token/api-key zal de access token/api-key in de Authorization: Token header opgenomen bij verzoeken.
Bij gebruik van OAuth2 dienen een client-id met client-secret combinatie beschikbaar te worden gesteld in combinatie met de endpoint waar deze combinatie gebruikt kan worden. Vervolgens zal conform de OAuth2 conventies de JWT worden doorgegeven via een Authorization: Bearer header bij de verzoeken.
Push
Om wijzigingen van objecten door te geven binnen een minuut nadat deze hebben plaatsgevonden is er de push-functionaliteit. Hiervoor dient de client conform de push-API openapi-spec wijzigingen aan te leveren. Met PUT worden volledige objecten bijgewerkt, terwijl middels PATCH alleen geleverde elementen worden bijgewerkt. Alleen voor tarieven is het mogelijk om objecten te verwijderen met een DELETE.
| Methode | Omschrijving | Location | EVSE | Connector | Tariff |
|---|---|---|---|---|---|
| PUT | Update objecten | x | x | x | x |
| PATCH | Update elementen van bestaande objecten | x | x | x | |
| DELETE | Verwijder objecten | x |
Het is niet toegestaan om identifiers van objecten te veranderen. Denk hierbij aan een PUT op een locatie met een parameter location_id met waarde x, terwijl het id-element van het object y is.
Push - Locaties
Voor het bijwerken van een enkele locatie is het mogelijk om een PUT of PATCH uit te voeren op de Locations, EVSE en Connector objecten. Daarbij is alleen de last_updated een verplicht element. Als er een sub-object benoemd wordt in een update dient dit sub-object volledig aanwezig te zijn (volgens de eisen van een PUT voor dat soort object).
Push - Tarieven
Voor het bijwerken van een enkel tarief is het mogelijk om een PUT uit te voeren op een Tariff-object. Voor het verwijderen van een tarief is het mogelijk om een DELETE uit te voeren, welke een HTTP-204 status code teruggeeft bij succes (dit verschilt van de OCPI-specificatie).
Push - Authenticatie
Warning
De credentials module van OCPI wordt niet gebruikt.
Authenticatie voor het leveren van de updates (push) verloopt via OAuth. Bij aanroep van de API moet een “OAuth token” worden meegestuurd. Via de NDW Identity & Access Management server kan een dergelijk OAuth token verkregen worden. Een NDW service account voor de DOT-NL API kunt u aanvragen bij de NDW servicedesk. Vermeld bij contact duidelijk dat het gaat om een "service account voor aanleveren DOT-NL".
Als u over een service account beschikt dan kan op de volgende wijze een OAuth token worden verkregen (via curl):
curl \
-d "client_id=<uw client_id>" \
-d "client_secret=<uw client secret>" \
-d "grant_type=client_credentials" \
https://iam.ndw.nu/auth/realms/ndw/protocol/openid-connect/token
Hierop volgt onderstaand response:
{
"access_token": "",
"expires_in": 1800,
"refresh_expires_in": 3600,
"refresh_token": "",
"token_type": "Bearer",
"not-before-policy": 0,
"session_state": "81ae1763-9c99-4c54-99b8-5e0629f8a2d6",
"scope": "profile email"
}
Het response bevat een access_token. De inhoud van dit access_token moet bij aanroep van de API worden meegestuurd. Dit kan middels de volgende HTTP header:
Authorization: Bearer <betreffende access token>
Push - Fout afhandeling
Als reactie op het pushen van data zijn er 2 reactie codes mogelijk, namelijk gerelateerd aan de communicatie (HTTP) en gerelateerd aan de inhoud (OCPI). Onderstaande tabel geeft inzicht in de te verwachten codes.
| Http-code | OCPI-status-code | |
|---|---|---|
| Verkeerde resource | 404 | - |
| Geen toegang | 401 | - |
| Geen valide json bericht | 400 | - |
| Json niet conform specificatie | 200 | 2xxx |
| Json conform specificatie | 200 / 201 | 1xxx |
Afnemen met OCPI-2.2.1
Voor het afnemen van de realtime data over de laadpunten is het mogelijk om aan te sluiten op de API.
API specificaties
Leverancier pull-API
Leverancier push-API
Afnemer pull-API
Servicedesk
Voor meer informatie kan contact opgenomen worden met de NDW Servicedesk.