Module Identifier: sessions
Data owner: CPO
Type: Functional Module
The Session object describes one charging session. The Session object is owned by the CPO back-end system, and can be GET from the CPO system, or pushed by the CPO to another system.
When the CPO creates a Session object they push it to the corresponding eMSP by calling PUT on the eMSP’s Sessions endpoint with the newly created Session object.
Any changes to a Session in the CPO system are sent to the eMSP system by calling PATCH on the eMSP’s Sessions endpoint with the updated Session object.
Sessions cannot be deleted, final status of a session is: COMPLETED.
When the CPO is not sure about the state or existence of a Session object in the eMSP’s system, the CPO can call GET on the eMSP’s Sessions endpoint to validate the Session object in the eMSP’s system.
eMSPs who do not support the Push model need to call GET on the CPO’s Sessions endpoint to receive a list of Sessions.
This GET method can also be used in combination with the Push model to retrieve Sessions after the system (re-)connects to a CPO, to get a list Sessions missed during a downtime of the eMSP’s system.
For a lot of smart charging use cases, input from the driver is needed. The smart charging algorithms need to be able to give certain session priority over others. In other words they need to know how much energy an EV needs before what time. Via a PUT request on the Sender Interface, during an ongoing session, the eMSP can send Charging Preferences on behalf of the driver.
The eMSP can determine if an EVSE supports Charging Preferences by checking if the EVSE capabilities contains: CHARGING_PREFERENCES_CAPABLE.
Via Tariffs the CPO can give different Charging Preferences different prices. A Connector can have multiple Tariffs, one for each ProfileType.
When a EV driver makes a Reservation for a Charge Point/EVSE, the Sender SHALL create a new Session object with status = RESERVED
When the Push model is used, the CPO SHALL push the new Session object to the Receiver.
When a reservation results in a charging session for the same Token, the Session object status to: ACTIVE
When a reservation does not result in a charging session, the Session object status SHALL be set to: COMPLETED.
A CDR might be created even if no energy was transferred to the EV, just for the costs of the reservation.
Typically implemented by market roles like: CPO.
| Method | Description |
|---|---|
Fetch Session objects of charging sessions last updated between the |
|
POST |
n/a |
Setting Charging Preferences of an ongoing session. |
|
PATCH |
n/a |
DELETE |
n/a |
Fetch Sessions from a CPO system.
Endpoint structure definition:
{sessions_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={limit}]
Examples:
https://www.server.com/ocpi/cpo/2.2.1/sessions/?date_from=2019-01-28T12:00:00&date_to=2019-01-29T12:00:00
https://ocpi.server.com/2.2.1/sessions/?offset=50
https://www.server.com/ocpi/2.2.1/sessions/?date_from=2019-01-29T12:00:00&limit=100
https://www.server.com/ocpi/cpo/2.2.1/sessions/?offset=50&limit=100
Only Sessions with last_update between the given {date_from} (including) and {date_to} (excluding) will be returned.
This request is paginated, it supports the pagination related URL parameters.
| Parameter | Datatype | Required | Description |
|---|---|---|---|
date_from |
yes |
Only return Sessions that have |
|
date_to |
no |
Only return Sessions that have |
|
offset |
int |
no |
The offset of the first object returned. Default is 0. |
limit |
int |
no |
Maximum number of objects to GET. |
The response contains a list of Session objects that match the given parameters in the request, the header will contain the pagination related headers.
Any older information that is not specified in the response is considered no longer valid. Each object must contain all required fields. Fields that are not specified may be considered as null values.
| Datatype | Card. | Description |
|---|---|---|
* |
List of Session objects that match the request parameters. |
Set/update the driver’s Charging Preferences for this charging session.
Endpoint structure definition:
{sessions_endpoint_url}/{session_id}/charging_preferences
Examples:
https://www.server.com/ocpi/cpo/2.2.1/sessions/1234/charging_preferences
|
Note
|
The /charging_preferences URL suffix is required when setting Charging Preferences.
|
The following parameter has to be provided as URL segments.
| Parameter | Datatype | Required | Description |
|---|---|---|---|
session_id |
CiString(36) |
yes |
Session.id of the Session for which the Charging Preferences are to be set. |
In the body, a ChargingPreferences object has to be provided.
| Type | Card. | Description |
|---|---|---|
1 |
Updated Charging Preferences of the driver for this Session. |
The response contains a ChargingPreferencesResponse value.
| Type | Card. | Description |
|---|---|---|
1 |
Response to the Charging Preferences PUT request. |
Typically implemented by market roles like: eMSP and SCSP.
Sessions are Client Owned Objects, so the endpoints need to contain the required extra fields: {party_id} and {country_code}.
Endpoint structure definition:
{sessions_endpoint_url}/{country_code}/{party_id}/{session_id}
Example:
https://www.server.com/ocpi/emsp/2.2.1/sessions/BE/BEC/1234
| Method | Description |
|---|---|
Retrieve a Session object from the eMSP’s system with Session.id equal to |
|
POST |
n/a |
Send a new/updated Session object to the eMSP. |
|
Update the Session object with Session.id equal to |
|
DELETE |
n/a |
The CPO system might request the current version of a Session object from the eMSP’s system to, for example, validate the state, or because the CPO has received an error during a PATCH operation.
The following parameters shall be provided as URL segments.
| Parameter | Datatype | Required | Description |
|---|---|---|---|
country_code |
CiString(2) |
yes |
Country code of the CPO performing the GET on the eMSP’s system. |
party_id |
CiString(3) |
yes |
Party ID (Provider ID) of the CPO performing the GET on the eMSP’s system. |
session_id |
CiString(36) |
yes |
id of the Session object to get from the eMSP’s system. |
The response contains the requested Session object.
| Datatype | Card. | Description |
|---|---|---|
1 |
Requested Session object. |
Inform the eMSP’s system about a new/updated Session object in the CPO’s system.
When a PUT request is received for an existing Session object (the object is PUT to the same URL), The newly received Session object SHALL replace the existing object.
Any charging_periods from the existing object SHALL be replaced by the charging_periods from the newly received Session object.
If the new Session object does not contain charging_periods (field is omitted or contains any empty list),
the charging_periods of the existing object SHALL be removed (replaced by the new empty list).
The request contains the new or updated Session object.
| Type | Card. | Description |
|---|---|---|
1 |
New or updated Session object. |
The following parameters shall be provided as URL segments.
| Parameter | Datatype | Required | Description |
|---|---|---|---|
country_code |
CiString(2) |
yes |
Country code of the CPO performing this PUT on the eMSP’s system. This SHALL be the same value as the |
party_id |
CiString(3) |
yes |
Party ID (Provider ID) of the CPO performing this PUT on the eMSP’s system. This SHALL be the same value as the |
session_id |
CiString(36) |
yes |
id of the new or updated Session object. |
Same as the PUT method, but only the fields/objects that need to be updated have to be present. Fields/objects which are not specified are considered unchanged.
Any request to the PATCH method SHALL contain the last_updated field.
The PATCH method of the Session Receiver interface works on the entire Session object only. It is not allowed to use extra URL segments to try to PATCH fields of inner objects of the Session object directly.
When a PATCH request contains the charging_periods field (inside a Session object),
this SHALL be processed as a request to add all the ChargingPeriod objects to the existing Session object.
If the request charging_periods list is omitted (or contains an empty list), no changes SHALL be made to the existing list of charging_periods.
If existing ChargingPeriod objects in
a Session need to be replaced or removed, the Sender SHALL use the PUT method to replace
the entire Session object (including all the charging_periods).
Patching the total_cost needs to be done on the Session Object.
PATCH https://www.server.com/ocpi/cpo/2.2.1/sessions/NL/TNM/101
link:examples/session_patch_example_total_cost.json[role=include]PATCH used to add a new ChargingPeriod to the Session and updating all related fields.
PATCH https://www.server.com/ocpi/cpo/2.2.1/sessions/NL/TNM/101
link:examples/session_patch_example_charging_period.json[role=include]The Session object describes one charging session. That doesn’t mean it is required that energy has been transferred between EV and the Charge Point. It is possible that the EV never took energy from the Charge Point because it was instructed not to take energy by the driver. But as the EV was connected to the Charge Point, some form of start tariff, park tariff or reservation cost might be relevant.
|
Note
|
Although OCPI supports such pricing mechanisms, local laws might not allow this. |
It is recommended to add enough ChargingPeriods to a Session so that the eMSP is able to provide feedback to the EV driver
about the progress of the charging session.
The ideal amount of transmitted Charging Periods depends on the charging speed.
The Charging Periods should be sufficient for useful feedback but they should not generate too much unneeded traffic either.
How many Charging Periods are transmitted is left to the CPO to decide. The following are just some points to consider:
-
Adding a new Charging Period every minute for an AC charging session can be too much as it will yield 180 Charging Periods for an (assumed to be) average 3h session.
-
A new Charging Period every 30 minutes for a DC fast charging session is not enough as it will yield only one Charging Period for an (assumed to be) average 30min session.
It is also recommended to add Charging Periods for all moments that are relevant for the Tariff changes, see CDR object description for more information.
For more information about how step_size impacts the calculation of the cost of charging also see the CDR object description.
| Property | Type | Card. | Description |
|---|---|---|---|
country_code |
CiString(2) |
1 |
ISO-3166 alpha-2 country code of the CPO that 'owns' this Session. |
party_id |
CiString(3) |
1 |
ID of the CPO that 'owns' this Session (following the ISO-15118 standard). |
id |
CiString(36) |
1 |
The unique id that identifies the charging session in the CPO platform. |
start_date_time |
1 |
The timestamp when the session became ACTIVE in the Charge Point. |
|
end_date_time |
? |
The timestamp when the session was completed/finished, charging might have finished before the session ends, for example: EV is full, but parking cost also has to be paid. |
|
kwh |
1 |
How many kWh were charged. |
|
cdr_token |
1 |
Token used to start this charging session, including all the relevant information to identify the unique token. |
|
auth_method |
1 |
Method used for authentication. This might change during a session, for example when the session was started with a reservation: ReserveNow: |
|
authorization_reference |
CiString(36) |
? |
Reference to the authorization given by the eMSP.
When the eMSP provided an |
location_id |
CiString(36) |
1 |
Location.id of the Location object of this CPO, on which the charging session is/was happening. |
evse_uid |
CiString(36) |
1 |
EVSE.uid of the EVSE of this Location on which the charging session is/was happening. Allowed to be set to: |
connector_id |
CiString(36) |
1 |
Connector.id of the Connector of this Location where the charging session is/was happening. Allowed to be set to: |
meter_id |
string(255) |
? |
Optional identification of the kWh meter. |
currency |
string(3) |
1 |
ISO 4217 code of the currency used for this session. |
charging_periods |
* |
An optional list of Charging Periods that can be used to calculate and verify the total cost. |
|
total_cost |
? |
The total cost of the session in the specified currency. This is the price that the eMSP will have to pay to the CPO. A total_cost of 0.00 means free of charge. When omitted, i.e. no price information is given in the Session object, it does not imply the session is/was free of charge. |
|
status |
1 |
The status of the session. |
|
last_updated |
1 |
Timestamp when this Session was last updated (or created). |
|
Note
|
Different authorization_reference values might happen when for example a ReserveNow had a different
authorization_reference then the value returned by a real-time authorization.
|
Contains the charging preferences of an EV driver.
| Property | Type | Card. | Description |
|---|---|---|---|
profile_type |
1 |
Type of Smart Charging Profile selected by the driver. The ProfileType has to be supported at the Connector and for every supported ProfileType, a Tariff MUST be provided. This gives the EV driver the option between different pricing options. |
|
departure_time |
? |
Expected departure. The driver has given this Date/Time as expected departure moment. It is only an estimation and not necessarily the Date/Time of the actual departure. |
|
energy_need |
? |
Requested amount of energy in kWh. The EV driver wants to have this amount of energy charged. |
|
discharge_allowed |
boolean |
? |
The driver allows their EV to be discharged when needed, as long as the other preferences are met: EV is charged with the preferred energy ( |
An enum with possible responses to a PUT Charging Preferences request.
If a PUT with ChargingPreferences is received for an EVSE that does not have the capability CHARGING_PREFERENCES_CAPABLE, the receiver should respond with an HTTP status of 404 and an OCPI status code of 2001 in the OCPI response object.
| Value | Description |
|---|---|
ACCEPTED |
Charging Preferences accepted, EVSE will try to accomplish them, although this is no guarantee that they will be fulfilled. |
DEPARTURE_REQUIRED |
CPO requires |
ENERGY_NEED_REQUIRED |
CPO requires |
NOT_POSSIBLE |
Charging Preferences contain a demand that the EVSE knows it cannot fulfill. |
PROFILE_TYPE_NOT_SUPPORTED |
|
Different smart charging profile types.
| Value | Description |
|---|---|
CHEAP |
Driver wants to use the cheapest charging profile possible. |
FAST |
Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed. |
GREEN |
Driver wants his EV charged with as much regenerative (green) energy as possible. |
REGULAR |
Driver does not have special preferences. |
Defines the state of a session.
| Value | Description |
|---|---|
ACTIVE |
The session has been accepted and is active. All pre-conditions were met: Communication between EV and EVSE (for example: cable plugged in correctly), EV or driver is authorized. EV is being charged, or can be charged. Energy is, or is not, being transfered. |
COMPLETED |
The session has been finished successfully. No more modifications will be made to the Session object using this state. |
INVALID |
The Session object using this state is declared invalid and will not be billed. |
PENDING |
The session is pending, it has not yet started. Not all pre-conditions are met. This is the initial state. The session might never become an active session. |
RESERVATION |
The session is started due to a reservation, charging has not yet started. The session might never become an active session. |