Module Identifier: sessions
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 push by the CPO to another system.
When the CPO creates a Session object they push it to the eMSPs by calling PUT on the eMSPs Sessions endpoint with the newly created Session object
Any changes to a Session in the CPO system are send to the eMSP system by calling PATCH on the eMSPs Sessions endpoint with the updated Session object
When the CPO deletes a Session, they will update the eMSPs systems by calling DELETE on the eMSPs Sessions endpoint, on the Sessions unique URL.
When the CPO is not sure about the state or existence of a Session object in the eMSPs system, the CPO can call the GET to validate the Session object in the eMSP system.
eMSPs who do not support the push model need to call GET on the CPOs Sessions endpoint to receive a list of Sessions.
Example endpoint structure: /ocpi/cpo/2.0/sessions/?date_from=xxx&date_to=yyy
Fetch Sessions from the CPO systems. Only Sessions with a start date/time between the given {date_from} and {date_to} will be returned.
This request is paginated, so also supports the pagination related URL parameters.
| Parameter | Datatype | Required | Description | |------------|---------------------------------------|----------|-------------------------------------------------------------------------------| | date_from | [DateTime](types.md#12_datetime_type) | yes | Begin charging session start Date/Time of the Sessions to fetch. | | date_to | [DateTime](types.md#12_datetime_type) | no | End charging session start Date/Time of the Sessions to fetch, if omitted all Sessions up to now are request to be returned. | | offset | int | no | The offset of the first object returned. Default is 0. | | limit | int | no | Maximum number of objects to GET. |NOTE: The CPO is allowed to return a (not specified) maximum amount of Sessions, to prevent overloading there system. In this version of OCPI it is not possible to detect if the CPO returned not all Sessions that match the filter.
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 as no longer valid. Each object must contain all required fields. Fields that are not specified may be considered as null values.
| Datatype | Card. | Description | |-------------------------------|-------|-------------------------------------------------------------------------| | [Session](#31-session-object) | * | List of Session objects that match the request parameters |Sessions is a client owned object, so the end-points need to contain the required extra fields: {party_id} and {country_code}.
Example endpoint structure:
/ocpi/emsp/2.0/sessions/{country_code}/{party_id}/{tariff_id}
The CPO system might request the current version of a Session object from the eMSP system for, for example validation purposes, or the CPO system might have received a error on a PATCH.
| Parameter | Datatype | Required | Description | |--------------|---------------------------------------|----------|-------------------------------------------------------------------------------| | country_code | [string](types.md#16-string-type)(2) | yes | Country code of the CPO requesting this PUT to the eMSP system. | | party_id | [string](types.md#16-string-type)(3) | yes | Party ID (Provider ID) of the CPO requesting this PUT to the eMSP system. | | session-id | [string](types.md#16-string-type)(15) | yes | id of the Session object to get from the eMSP system. |The response contains the request Session object, if available.
| Datatype | Card. | Description | |-------------------------------|-------|---------------------------------------------------------------| | [Session](#31-session-object) | 1 | Session object requested. |Inform the system about a new/updated session in the eMSP backoffice by PUTing a Session object.
The request contains the new or updated Session object.
| Type | Card. | Description | |---------------------------------|-------|------------------------------------------| | [Session](#31-session-object) | 1 | new Session object. | | Parameter | Datatype | Required | Description | |--------------|---------------------------------------|----------|-------------------------------------------------------------------------------| | country_code | [string](types.md#16-string-type)(2) | yes | Country code of the CPO requesting this PUT to the eMSP system. | | party_id | [string](types.md#16-string-type)(3) | yes | Party ID (Provider ID) of the CPO requesting this PUT to the eMSP system. | | session-id | [string](types.md#16-string-type)(15) | yes | id of the new or updated Session object. |Same as the PUT method, but only the fields/objects that have to be updated have to be present, other fields/objects that are not specified are considered unchanged.
PATCH To URL: https://www.server.com/ocpi/cpo/2.0/sessions/NL/TNM/101
{
"total_cost": "0.60"
}Inform the eMSP about a deleted Session object.
| Parameter | Datatype | Required | Description | |--------------|---------------------------------------|----------|-------------------------------------------------------------------------------| | country_code | [string](types.md#16-string-type)(2) | yes | Country code of the CPO requesting this PUT to the eMSP system. | | party_id | [string](types.md#16-string-type)(3) | yes | Party ID (Provider ID) of the CPO requesting this PUT to the eMSP system. | | session-id | [string](types.md#16-string-type)(15) | yes | ID of the Session to be deleted | | Property | Type | Card. | Description | |--------------------------------|------------------------------------------------------------|-------|----------------------------------------------------------------------------------------------------------------| | id | [string](types.md#16-string-type)(15) | 1 | The unique id that identifies the session in the CPO platform. | | start_datetime | [DateTime](types.md#12_datetime_type) | 1 | The time when the session became active. | | end_datetime | [DateTime](types.md#12_datetime_type) | ? | The time when the session is completed. | | kwh | [decimal](types.md#13_decimal_type) | 1 | How many kWh are charged. | | auth_id | [string](types.md#16-string-type)(15) | 1 | An id provided by the authentication used, so that the eMSP knows to which driver the session belongs. | | auth_method | [AuthMethod](mod_cdrs.md#41-authmethod-enum) | 1 | Method used for authentication. | | location | [Location](mod_locations.md#31-location-object) | 1 | The location where this session took place, including only the relevant EVSE and connector | | meter_id | [string](types.md#16-string-type)(255) | ? | Optional identification of the kWh meter. | | currency | [string](types.md#16-string-type)(3) | 1 | ISO 4217 code of the currency used for this session. | | charging_periods | [ChargingPeriod](mod_cdrs.md#43-chargingperiod-class) | * | An optional list of charging periods that can be used to calculate and verify the total cost. | | total_cost | [decimal](types.md#13_decimal_type) | 1 | The total cost (excluding VAT) of the session in the specified currency. This is the price that the eMSP will have to pay to the CPO. | | status | [SessionStatus](#41-sessionstatus-enum) | 1 | The status of the session. |{
"id": "101",
"start_datetime": "2015-06-29T22:39:09+02:00",
"kwh": "0.00",
"auth_id": "FA54320",
"location": {
"id": "LOC1",
"type": "on_street",
"name": "Gent Zuid",
"address": "F.Rooseveltlaan 3A",
"city": "Gent",
"postal_code": "9000",
"country": "BE",
"coordinates": {
"latitude": "3.72994",
"longitude": "51.04759"
},
"evse": {
"uid": "3256",
"evse_id": "BE-BEC-E041503003",
"STATUS": "AVAILABLE",
"connectors": [{
"id": "1",
"standard": "IEC_62196_T2",
"format": "SOCKET",
"power_type": "AC_1_PHASE",
"voltage": "230",
"amperage": "64",
"tariff_id": "11"
}]
}
},
"currency": "EUR",
"total_cost": "2.50",
"status": "PENDING"
}{
"id": "101",
"start_datetime": "2015-06-29T22:39:09+02:00",
"end_datetime": "2015-06-29T23:50:16+02:00",
"kwh": "0.00",
"auth_id": "FA54320",
"location": {
"id": "LOC1",
"type": "on_street",
"name": "Gent Zuid",
"address": "F.Rooseveltlaan 3A",
"city": "Gent",
"postal_code": "9000",
"country": "BE",
"coordinates": {
"latitude": "3.72994",
"longitude": "51.04759"
},
"evse": {
"uid": "3256",
"evse_id": "BE-BEC-E041503003",
"STATUS": "AVAILABLE",
"connectors": [{
"id": "1",
"standard": "IEC_62196_T2",
"format": "SOCKET",
"power_type": "AC_1_PHASE",
"voltage": "230",
"amperage": "64",
"tariff_id": "11"
}]
}
},
"connector_id": "1",
"currency": "EUR",
"charging_periods": [{
"start_date_time": "2015-06-29T22:39:09+02:00",
"dimensions": [{
"type": "ENERGY",
"volume": 120
}, {
"type": "MAX_CURRENT",
"volume": 30
}]
}, {
"start_date_time": "2015-06-29T22:40:54+02:00",
"dimensions": [{
"type": "energy",
"volume": 41000
}, {
"type": "MIN_CURRENT",
"volume": 34
}]
}, {
"start_date_time": "2015-06-29T23:07:09+02:00",
"dimensions": [{
"type": "PARKING_TIME",
"volume": 0.718
}]
}],
"total_cost": "8.50",
"status": "COMPLETED"
}Describe all datatypes used in this object
| Property | Description | |-----------|----------------------------------------------------------------------------| | ACTIVE | The session is accepted and active. | | COMPLETED | The session has finished successfully. | | INVALID | The session is declared invalid and will not be billed. | | PENDING | The session is pending and has not yet started. This is the initial state. |