In this article, we will show you the best practices and web services to set up an EMP. Before we start, please note the following points:
- 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 OpenAPI specification. 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.
- Implement eRoamingEvseData (static data) and eRoamingEvseStatus (dynamic data) to obtain the charge point information
- Implement the Authorization web service to perform authorization
- Implement the pull Charge Detail Record (CDR) for billing information
- The implementation of eRoaming Reservation is optional.
- Test and check the web services using the HBS Process Monitor
EVSEData & Status
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 return a large number of items. Our OICP 2.3 automatically paginates the results of large requests to make this easier to parse.
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 to 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 the 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 the Service Subscriptions view.
Collecting the EvseData filtering by country
If you are interested in receiving the data for a specific 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.
Collecting the EVSEData that has been updated after a specific date
You can also search for EVSEData that has been updated after a specific date of your choosing to limit the size of the response.
In this example, you will receive the EVSEdata that has been changed after January 23, 2022 at 2.27 PM UTC.
The deltaType will indicate whether the EVSE has been updated, inserted or deleted.
Filtering by authentication mode
Let’s look for charging stations that allow Plug&Charge. In this case, you can enter the value PnC in the 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 setting up a daily frequency for PullEvseData requests.
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 receive can be found in our OICP documentation.
For example, when a charging session is started successfully via the 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
The PullEvseStatusByID request allows you to receive the status for a specific EvseID.
How to receive the status for the charging stations from a specific CPO or list of CPOs
You can use the parameter OperatorIds to filter by the OperatorID of a CPO. This parameter allows you to provide a list of OperatorIDs. This will be useful to retrieve only the data from the CPOs that you are subscribed to.
What frequency should I set?
We recommend you set up a 2 or 3 minutes frequency to keep the status updated in your app.
eRoamingAuthorizeStart requests are sent by the CPOs when an EV driver swipes an RFID card on a charging station. As soon as the request is received in our HBS platform it will be forwarded to the EMPs for 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 a request and response can be found in the code snippets.
The response should be sent within 10 seconds otherwise our system will consider it a time-out.
For more information about our time outs, please refer to the article What are the time outs in Hubject?
What should I check if I am not receiving AuthorizeStart requests?
In case you are having issues receiving AuthorizeStart requests we recommend you check the following:
- The endpoint URL in Service Type Settings for Authorization is 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 the “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 contact the Hubject support team.
As EMP you will receive an eRoamingAuthorizeStop request when a charging session that has been started by RFID is stopped using the same medium. A charging session that has been started via the app can be also stopped offline. This web service is optional for CPOs and you may not receive it in some cases.
eRoamingAuthorizeRemoteStart request allows you to start a charging session via the app.
Let’s say one of your customers is located in front of a charging station and scans 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 the “Start Charging” button.
When clicking on the button, an AuthorizeRemoteStart request will be sent 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 at least one EVCO ID per customer.
- 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 this request, otherwise, Hubject will finish the process with a Time Out Error. We recommend you adjust your time out accordingly.
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.
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 the Forwarding Status column in the process monitor. In case an error occurs, the CDR will not be resent.
You can request the NOT_FORWARDED CDRs using GetChargeDetailRecords or the export option in the process monitor.
Next, read about how to request an implementation meeting (optional).