Connection / Data Submission

To connect to DOT-NL, please contact the NDW Servicedesk. Indicate that your request concerns connecting to DOT-NL or NAP-EV. Coordination will then take place on how the connection will be set up, and connection tests will be performed. The connection process broadly follows these steps:

1. Receive pull credentials
   1. Validation whether locations comply with the connection schemas
   2. Validation whether tariffs comply with the connection schemas
2. Connect data delivery to the NDW staging environment
3. Once data delivery is approved, connect to the NDW production environment
4. Push credentials for the staging environment are provided by NDW
   1. Validation whether locations are pushed correctly (PUT/PATCH)
   2. Validation whether tariffs are pushed correctly (PUT/DELETE)
5. Once data delivery is approved, connect to the NDW production environment

Connection Schemas

Download tariff schema

Download locations schema

Data Submission with OCPI 2.2.1

OCPI (Open Charge Point Interface) is a protocol that enables communication between charging point operators and service providers and is maintained by the EVRoaming Foundation.

For delivery to DOT-NL using OCPI‑2.2.1, OpenAPI specifications have been defined for both pull and push functionality (section 4.1.3 in OCPI‑2.2.1). These specifications describe which information is expected via which endpoints (see further down this page at API specifications).

The schemas that CPOs must comply with can be found above. Delivery to DOT-NL is currently supported only in OCPI version 2.2.1.

Pull

To obtain the complete set of objects and the latest state of individual objects, NDW periodically (daily) retrieves these using the pull functionality available in OCPI. For this purpose, a server must be available that returns the current state in response to a GET, in accordance with the pull-API OpenAPI specification.

Pull – Locations

For supplying Locations, an endpoint must be available that listens to requests for both the complete set and individual locations. Retrieving individual EVSE and Connector objects is not currently used.

Pull – Tariffs

For supplying Tariffs, an endpoint must be available that listens to requests for the complete set of tariffs.

Pull – Authentication

To retrieve the current state from the supplier, authentication details must be provided. Access can be granted in two ways: via a token/API key or via OAuth2.

When using an agreed token/API key, the access token/API key must be included in the Authorization: Token header of requests.

When using OAuth2, a client_id and client_secret combination must be provided, along with the endpoint where this combination is used. In accordance with OAuth2 conventions, the JWT is then passed in an Authorization: Bearer header with each request.

Push

To communicate changes to objects within one minute after they occur, the PUSH functionality is available. For this, the client must submit changes in accordance with the push-API OpenAPI specification. PUT updates full objects, while PATCH updates only the supplied elements. Only tariffs can be deleted using DELETE.

It is not permitted to change identifiers of objects. For example, performing a PUT on a location with parameter location_id set to x while the id element of the object is y.

Push – Locations

To update a single location, a PUT or PATCH can be performed on Location, EVSE, and Connector objects. Only last_updated is mandatory. If a sub-object is included in an update, that sub-object must be complete (according to PUT requirements for that object type).

Push – Tariffs

To update a single tariff, a PUT can be performed on a Tariff object. To delete a tariff, a DELETE can be performed, which returns an HTTP‑204 status code on success (NOTE: this differs from the OCPI specification).

Push – Authentication

Authentication for delivering updates (PUSH) is handled via OAuth. An OAuth token must be included with API calls. Such a token can be obtained from the NDW Identity & Access Management server.

An NDW service account for the DOT‑NL API can be requested via the NDW Servicedesk. When contacting them, clearly state that the request concerns a “service account for DOT‑NL data submission.”

Once you have a service account, an OAuth token can be obtained as follows (via curl):

curl \
  -d "client_id=<your client_id>" \
  -d "client_secret=<your client secret>" \
  -d "grant_type=client_credentials" \
  https://iam.ndw.nu/auth/realms/ndw/protocol/openid-connect/token

This returns the following 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"
}

The response contains an access_token. This token must be included when calling the API using the following HTTP header: Authorization: Bearer <relevant access token>.

By default, the token is valid for 30 minutes and does not need to be refreshed for every update.

Push – Error Handling

In response to pushing data, two types of status codes may be returned: communication-related (HTTP) and content-related (OCPI). The table below shows an overview of these codes.

Timeliness

The supplied data must be up to date. This means that changes to static data must be applied within 24 hours, while changes to dynamic data must be delivered within 1 minute.

API Specifications

Supplier pull API

To connect as a supplier, the following API specification has been defined and must be implemented by the supplier as a server.

Supplier push API

To update information as a supplier, the following API specification has been defined and must be implemented by the supplier as a client.

Servicedesk

For more information, questions, or connecting to the NAP, please contact the NDW Servicedesk.