Skip to main content

2.10 Web services to be implemented as CPO

Antonio Acuña
Updated

In this article, we'll show you best practices and web services to set up as CPO. Before we start, there’s a couple of important details:

  • It’s necessary to use the signed certificate for calls from your backend to our HBS platform (e.g. PushEvseData).
  • Your IP addresses have been provided via IT ticket and you have received a confirmation from the Hubject support team.
  • We recommend you ensure that the communication between your server and our endpoints 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.
Which section are you looking for?

 

EvseData & Status


PushEvseData

Let’s start pushing the static data of the charging stations you would like to include in the Intercharge network.

 

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

 

pushEvseData.png

 

You can work with PushEvseData requests using the following actions:

  • FullLoad: you can upload all your charging stations at once using a fullLoad.
  • Insert: you can use this action to upload some specifics charging stations after a fullLoad action.
  • Update: this action type can be used to update one or some the values included in the parameters related to one or some specific charging points.
  • Delete: it can be used to delete one or more EvseIDs included in the EvseData.

Please note that a PushEvseData request with action type fullLoad will overwrite the previous data uploaded.

 

Uploading the EvseData for the first time

To upload your EvseData information for first time you need to choose the ActionType "FullLoad". You can follow the steps below.

  1. Set up a PushEvseData request with at least all the mandatory parameters. In order to provide detailed information about the charging points to the EMPs we recommend to fill in as many parameters as possible.
  2. Send the request to the endpoint URL specified in the code snippets.
  3. If the data has been uploaded successfully you will receive a response with status code 000 (Success).

Please check that the values included in the parameters match the specifications defined in the OICP documentation.

Our system will return an HTTP error 400 (Bad request) with the description of the validation error if one or more values included in the body of the request don't match the specifications.

uploaing evse.png

 

How can a new charging point be added if a fullLoad has been already sent?

One or more charging points can be added using the action type "insert" after sending a PushEvseData request with action type fullLoad.

 

The charging points must be added later in the next PushEvseData request with action type fullLoad.

 

When should a request with action type "update" be sent?

Let's say that one of the EMPs has reported that the coordinates for a specific charging point are wrong.

 

In this case a PushEvseData request can be sent with action type "update" including the information related to the charging point to be modified.

 

Please note that the information must be also updated in the next request with action type fullLoad.

 

What frequency should I set?

We recommend setting up a weekly frequency for PushEvseData requests with action type fullLoad.
PushEvseData requests with action type "insert" and "update" can be sent when it's needed.

 

note, text icon What you need to know

  • We highly recommend to assign an EvseID per plug when it's possible.
  • Make sure you do not include duplicated EvseIDs otherwise you will receive a status code 018 - Duplicate EVSE IDs
  • Make sure you have registered a sub-partner before uploading the charging points belonging to it.
  • Status code 022 - One ore more EVSE data not found, cannot execute delete is sent when you are trying to delete or update an EvseID that it's currently not included in your EvseData. Please check all the EvseIDs you want to delete are included in your EvseData.
  • You can use the download payload functionality included in the process monitor to download the PushEvseData requests sent.
  • The HBS platform normalizes the EvseID by default so the * it will not be taken in consideration. For example, the EvseID DE*XWZ*E00000*01 and DE*XWZ*E0000*001 would be considered as a duplicate. Both EvseIDs will match with the EvseID DEXWZE0000001. In this case the system returns a status code 018 - Duplicated EvseIDs.

 

 

PushEvseStatus

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

PushEvseStatus.png

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

 

You can work with PushEvseData requests using the following actions:

  • FullLoad: you can send all the statuses at once using a fullLoad.
  • Update: this action type can be used to update the status when it changes for a specific charging station.

Scenario

  1. The EV-Driver arrives to the charging station and start a charging session via EMP app.
  2. The AuthorizeRemoteStart request is received successfully and the EV-Driver plug the cable.
  3. The charging station send a status update "Occupied" and it's forwarded to the HBS platform via PushEvseStatus request with ActionType "update".
  4. After the charging session an update with the status "Available" should be sent.

What frequency should I set?

We recommend to set up a daily fullLoad with including the status for all the charging stations in order to syncronize the EvseStatus with the EvseData.

For example, you can set up a weekly fullLoad for EvseData at 06:00 AM and a daily fullLoad for EvseStatus at 06:02 AM.

In case you insert one or more charging stations via PushEvseData you should send a PushEvseStatus request with the status afterwards.

 

note, text icon What you need to know

  • PushEvseStatus requests with ActionType "update" should only be sent when the status change.
  • The EvseID for which the status is sent must be included in the EvseData. Otherwise you will receive a status code 603 - One ore more EVSE data record not found! 

 

 

 

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.

AuthorizeStart.png

authorizestart2.png

 

As CPO you will send the necessary parameters in the AuthorizeStart request to identify if the request belongs to one of EMPs subscribed to your offer. An example of request and response can be found in the code snippets.

 

The response will be sent within 10 seconds. For more information about our time outs, please refer to the article What are the time outs in Hubject?

 

Scenario

  1. The EV-Driver swipes the RFID card on the RFID reader.
  2. The AuthorizeStart request is sent to the CPO backend and forwarded to the HBS platform.
  3. The request is sent via broadcast to all the EMPs subscribed to the offer.
  4. One of the EMPs subscribed to the offer sends an Authorized response.
  5. The EV-Driver plug the cable and the charging session start.
  6. A PushEvseStatus request with status update "Occupied" is sent.
  7. EV-Driver unplug the cable and finish the charging session.
  8. A CDR with the details of the charging session must be sent.
  9. A PushEvseStatus request wiht status update "Available" should be sent.

 

note, text icon Hubject provides the CPOs a testing packet during the onboarding process to test AuthorizeStart requests. In case you haven't received it, please get in touch with your onboarding manager.

 

What happen if the charging session fails?

You should generate a CDR with 0 consumption to close the session in the HBS platform and EMP side. The CDR can be sent within the 90 days since the AuthorizeStart request is sent. We highly recommend to send it before the limit.

 

What should I check if I am not receiving a response when sending 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.

 

note, text icon What you need to know

  • We highly recommend to include the EvseID in AuthorizeStart requests when it's possible. If it's not possible to provide it in the AuthorizeStart request (e.g. one reader for more than one plug) you can provide it in a second request via ChargingNotification.
  • Only one AuthorizeStart request per charging session should be sent.
  • Please check the validation error in case an HTTP error 400 is received when sending the AuthorizeStart request. Probably one or more values provided don't match the OICP specifications.
  • The CDR should be sent within 60 seconds after the charging session ends.

 

 

AuthorizeStop

As CPO you will send 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.

 

AuthorizeRemoteStart

eRoamingAuthorizeRemoteStart request allow the EMP to start a charging session via app.

 

Let’s say one of the EMP 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.

 

remoteStart.png

 

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 the CPO should return a status code 000 (Success).

remoteStart 2.png

 

Scenario

  1. The EMP sends an AuthorizeRemoteStart request via app
  2. The AuthorizeRemoteStart request is sent to the HBS platform and forwarded to the CPO backend.
  3. The CPO returns a status code 000 (Success).
  4. The EV-Driver plug the cable and the charging session start.
  5. A PushEvseStatus request with status update "Occupied" is sent.
  6. The charging sessoin is stopped via AuthorizeRemoteStop reques.
  7. The CPO returns a status code 000 (Success) as response.
  8. The EV-Driver unplug the cable and finish the charging session.
  9. A CDR with the details of the charging session must be sent.
  10. A PushEvseStatus request wiht status update "Available" should be sent.

AuthorizeRemoteStop

This request is sent in order to stop an active charging session. Please check the code snippets to know the parameters included in the request.

 

note, text icon As CPO you can test this type of request with the Remote Testing Tool integrated in the HBS platform. The E2E test cases with app should be also completed using this app.

 

ChargeDetailRecord

The CPO send 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.

 

cdr.png

 

We have implemented CDRs quality check in order to provide a better service for all partners and the following conditions are not allowed:

  1. maximal possible consumed energy value (>700 kWh)

  2. Consumed Energy < 0

  3. Meter Value End - Meter Value Start > maximal possible consumption

  4. Meter Value End < Meter Value Start

  5. Charging End < Charging Start

  6. Session End < Session Start

If any of the conditions described above are met, the system will return an error 022 - Data error.

 

note, text icon What you need to know

  • The CDR cannot be resent as soon as the session has the status CLOSED. You will receive a status code 400 - Session found but status is not valid CLOSED! in the response.
  • We recommend to implement the parameters EMPPartnerSessionID and CPOPartnerSessionID. You will receive the EMPPartnerSessionID in AuthorizeStart and AuthorizeRemoteStart requests.
  • If you became an Interchage Settlement partner you should implement the parameter PartnerProductID.

 

ChargingNotification

This feature enables CPO to send various notifications during a single Charging Session. These notifications give the details like

  1. When the charging session has started. The CPO can send ChargingNotification of type “Start” to Hubject containing information like ChargingStart, MeterStartValue, EVSEID etc.

  2. Consumed Energy values during the charging process or duration of successful charging process that has lapsed. The CPO can send ChargingNotification of type “Progress” to Hubject containing information like ChargingStart, EventOccurred, ChargingDuration, ConsumedEnergyProgress, EVSEID etc. The frequency between two progress notifications for one charging session should be at least 5 minutes.

  3. When the charging session has ended (because no energy is transmitted anymore). The CPO can send a ChargingNotification of type “End” to Hubject containing information such as ChargingEnd, ConsumedEnergy, EVSEID etc.

  4. Error occurred before charging starts or during charging process or abrupt changing end. The CPO can send a ChargingNotification of type “Error” to Hubject containing information such as ErrorClass, ErrorAdditionalInfo, EVSEID etc.

Hubject will forward Start, Progress, End and Error notification requests to the EMP. The EMP responds with an eRoamingAcknowledgement. This acknowledgement is then being forwarded to the CPO.

This feature should cover all the notifications that could happen between Session Start and Session End in future. Each bit of information increases transparency to the customer of EMP.

 

Scenario

  1. The EMP sends an AuthorizeRemoteStart request via app
  2. The AuthorizeRemoteStart request is sent to the HBS platform and forwarded to the CPO backend.
  3. The CPO returns a status code 000 (Success).
  4. The EV-Driver plug the cable and the charging session start.
  5. A PushEvseStatus request with status update "Occupied" is sent.
  6. ChargingNotification of type "Start" is sent.
  7. After 5 minutes a ChargingNotfication of type "Progress" is sent.
  8. The charging session is stopped via AuthorizeRemoteStop request.
  9. The CPO returns a status code 000 (Success) as response.
  10. A ChargingNotification of type "End" is sent.
  11. The EV-Driver unplug the cable and finish the charging session.
  12. A CDR with the details of the charging session must be sent.
  13. A PushEvseStatus request wiht status update "Available" should be sent.

 

note, text icon ChargingNotification requests are displayed in the Sessions view of the process monitor.

Related articles