Aansluiten / Aanleveren

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. Het aansluitproces volgt globaal de volgende stappen:

1. Pull credentials ontvangen
   1. Controle of de locaties voldoen aan de aansluitschema's
   2. Controle of de tarieven voldoen aan de aansluitschema's
2. Data levering aansluiting op NDW staging omgeving
3. Wanneer goedbevonden data levering aansluiten op NDW productieomgeving
4. Push credentials richting staging omgeving worden door NDW gedeeld
   1. Controle of de locaties correct gepushed worden (PUT/PATCH)
   2. Controle of de tarieven correct gepushed worden (PUT/DELETE)
5. Wanneer goedbevonden data levering aansluiten op NDW productieomgeving

Aansluitschema's

Download tariff schema

Download locations schema

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 beschrijven welke informatie per endpoint wordt verwacht (zie onderaan deze pagina bij API specificaties.

De schema's waaraan CPO's moeten voldoen zijn hierboven terug te vinden. Levering aan DOT-NL wordt, momenteel, alleen ondersteund in OCPI versie 2.2.1

Pull

Om de volledige set van objecten en de laatste stand van individuele objecten te weten, worden deze door NDW periodiek (dagelijks) opgehaald d.m.v. de pull-functionaliteit aanwezig in OCPI. De leverancier dient hiervoor een server beschikbaar te stellen die conform de pull-API OpenAPI-specificatie de huidige toestand retourneert in response op een GET-verzoek.

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 luistert naar verzoeken voor de volledige set van tarieven.

Pull - Authenticatie

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 toegang te verlenen, namelijk d.m.v. een token/api-key of d.m.v. OAuth2.

Bij gebruik van een afgesproken token/api-key zal de access token/api-key in de Authorization: Token header moeten worden opgenomen bij het insturen van 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 moeten worden doorgegeven via een Authorization: Bearer header bij het insturen van de verzoeken.

Push

Om wijzigingen van objecten door te kunnen 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.

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 (LET OP: dit is anders dan wat de OCPI-specificatie voorschrijft).

Push - Authenticatie

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 de onderstaande 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"
}

De response bevat een access_token. De inhoud van dit access_token moet bij aanroep van de API worden meegestuurd. Dit kan d.m.v. de volgende HTTP header: Authorization: Bearer <betreffende access token>.

Standaard is het token 30 minuten geldig, dit hoeft niet bij elke update te worden ververst.

Push - Fout afhandeling

Bij het pushen van data kunnen zowel HTTP‑statuscodes als OCPI‑statuscodes worden geretourneerd. Onderstaande tabel toont het overzicht van deze codes.

Tijdigheid

De aangeleverde data dient actueel te zijn. Dit wil zeggen dat voor statische gegevens wijzigingen binnen 24 uur moeten plaatsvinden, dynamische gegevens wijzigingen dienen binnen 1 minuut aangeleverd te worden.

API specificaties

Leverancier pull-API

Voor het aansluiten als leverancier is onderstaande API-specificatie opgesteld, deze dient door de leverancier te worden geïmplementeerd als server.

Leverancier push-API

Voor het updaten van informatie als leverancier is de volgende API-specificatie opgesteld, deze dient door de leverancier te worden geïmplementeerd als client.

Servicedesk

Voor meer informatie, vragen of aansluiten op het NAP kan contact opgenomen worden met de NDW Servicedesk.