2.7 Implementation of web services – Hubject

In this article, we will show you best practices and web services to set up as EMP.

Prerequisites

It is necessary to use the signed certificate for calls from your backend to our HBS platform (e.g. PullEvseData).
You have provided your IP addresses to your Onboarding manager and have received whitelisting confirmation.
Please ensure that the communication between your server and our endpoint URL has been set up properly.

You can find examples for each request and endpoint URLs in the code snippets.
A detailed description of the web services can be found in the OICP documentation. Please follow this documentation during the implementation of the web services.
We have specified call limits for these web services in our Acceptable Use Policy. Please find it on GitHub.

Web services checklist

Implement the Authorization web service to perform authorization
Implement eRoamingEvseData (static data) and eRoamingEvseStatus (dynamic data) to obtain the charge point information
Implement the pull Charge Detail Record for information relevant to the accounting process
The implementation of eRoaming Reservation is optional.
Test and check the web services using the HBS Process Monitor
Check your web service frequency (PushAuthorizationData, PullEvseStatus, PullEvseData) in the HBS Process Monitor and record it in the Web Service Checklist
Email the Web Service Checklist (you can find it at the bottom of this article) to onboarding@hubject.com

Web services

EvseData & Status Authorization

EvseData & Status

PullEvseData

Let’s start pulling the static data of the charging stations included in our intercharge network.

PullEvseData request allows you to collect the static information of the charging stations (e.g. address, plug type…). This type of information is called EvseData.

Many of the PullEvseData requests will have a large number of items returned in the results. In order to make this easier to deal with, our OICP 2.3 automatically paginates the results of large requests.

When this happens, you will receive part of the result, followed by a URL. By default you will receive 20 records in the response. You can set up a maximum of 2000 records per page and send a maximum of 25 requests per minute.

The EvseData can be received without being subscribed to an authorization offer from a specific CPO.

How to collect the EvseData from one or some specific CPOs

For example, let’s say you want to collect the EvseData from the CPOs you are subscribed in other to show this information in your app.

You can send a PullEvseData request filtering by OperatorID. A list with the OperatorIDs of the CPOs you are subscribed can be entered in OperatorIds parameter. In the response you will only receive the EvseData from the requested CPOs.

The OperatorIDs of the CPOs you are subscribed can be found using the export option included in Service Subscriptions view.

Collecting the EvseData filtering by country

If you are interested on receiving the data for a specific or list of countries you can use the CountryCodes parameter. A list of different country codes can be provided. Please note that this filter cannot be combined with SearchCenter, OperatorIDs and LastCall.

Filtering by authentication mode

Let’s look for the charging stations that allow Plug & Charge. In this case you can enter the value PnC in AuthenticationModes parameter and only the charging stations that include this authentication option will be received in the response. The other possible values can be found here.

What frequency should I set?

We recommend to set up a daily frequency for PullEvseData requests.

PullEvseStatus

Charging stations send dynamic data to our HBS platform, this type of information is called EvseStatus. As EMP you can collect the status of the charging stations via PullEvseStatus requests.

The different parameters and values that you can received can be found in our OICP documentation.

For example, when a charging session is started successfully via EMP app the CPO will push the status “Occupied” to our HBS platform. The EMPs can receive this information via PullEvseStatus request and update the status in their app.

How to receive the status for a specific charging station

PullEvseStatusByID request allow you to receive the status for an specific EvseID.

How to receive the status for the charging stations from a specific or list of CPOs

You can use the parameter OperatorIds to filter by the OperatorID of a CPO. This parameter allow you to provide a list of OperatorIDs. This will be useful to retrieve only the data from CPOs that you are subscribed.

What frequency should I set?

We recommend you to set up a 2 or 3 minutes frequency to keep the status updated in your app.

Authorization

AuthorizeStart

eRoamingAuthorizeStart requests are sent by the CPOs when an EV-Driver swipe a RFID card on a charging station. As soon as the request is received in our HBS platform it will be forwarded to the EMPs which the CPO has a valid contract.

As EMP you will receive the necessary information in the AuthorizeStart request to identify if the request belongs to one of your customers. An example of request and response can be found in the code snippets.

The response should be sent within 10 seconds otherwise our system will consider it as a time out.
For more information about our time outs, please refer to the article What are the time outs in Hubject?

We have recently implemented a Virtual Charging Station to help the EMPs to test the AuthorizeStart requests. For more information, please refer to the article Virtual Charging Point.

What should I check if I am not receiving AuthorizeStart requests?

In case you are having issues receiving AuthorizeStart requests we recommend you to check the following:

The endpoint URL in Service Type Settings for Authorization in configured correctly. Online requests and broadcast options should be activated.
Your endpoint URL is providing the same certificate that you have uploaded in the certificate management or is providing our Hubject_CA in case you have selected “Hubject Certificate” option.
In case you are using an internal firewall, please be sure that our fixed IPs are included in your whitelist.

If the problem persists, please feel free to contact the Hubject support team.

AuthorizeStop

As EMP you will receive an eRoamingAuthorizeStop request when a charging session that it has been started by RFID is stopped using the same medium. A charging session that it has been started via app can be also stopped offline. This web service is optional for CPOs and you may not receive it in some cases.

AuthorizeRemoteStart

eRoamingAuthorizeRemoteStart request allow you to start a charging session via app.

Let’s say one of your customers is located in front of a charging station and scan the QR-Code included in the Intercharge sticker using the QR-reader included in the app.

The information related to the charging point will be displayed (e.g. plug type, address, status…). If the status is available, the customer will have the option to start the charging session by clicking on “Start Charging” button.

When clicking on the button, an AuthorizeRemoteStart request will be send to the HBS platform from the EMP backend. If there is a valid subscription the request will be forwarded to the CPO. If the request is received successfully you will receive a status code 000 (Success).

We recommend the following:

You should assign an EVCOID per customer. The regular expression can be found in our OICP documentation.
The EvseID should be included in the CPO's EvseData. Otherwise, you will receive an error 603 – “Unknown EvseID”.
The CPO has 40 seconds to answer to this request, otherwise Hubject will finish the process with a Time Out Error. We recommend you to adjust your time out accordingly.

AuthorizeRemoteStop

This request is sent in order to stop an active charging session. The SessionID and EvseID will be required.

You can test AuthorizeRemoteStart/Stop requests using our Virtual Charging Station.

ChargeDetailRecord

The CPO sends a ChargeDetailRecord (CDR) at the end of the charging session with the charging process details. As soon as the CDR is received our HBS platform will be forwarded to the EMP.

The CDR will be forwarded to the endpoint URL set up in Service Type Settings for Authorization.

As EMP you can check if the forwarding of a CDR has been successful in Forwarding Status column in the process monitor. In case an error occurs, the CDR will not be resent.