Skip to content

Latest commit

 

History

History
326 lines (253 loc) · 17 KB

mod_sessions.md

File metadata and controls

326 lines (253 loc) · 17 KB

Sessions module

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.

1. Flow and Lifecycle

1.1 Push model

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.

1.2 Pull model

eMSPs who do not support the push model need to call GET on the CPOs Sessions endpoint to receive a list of Sessions.

2. Interfaces and endpoints

2.1 CPO Interface

Example endpoint structure: /ocpi/cpo/2.0/sessions/?date_from=xxx&date_to=yyy

| Method | Description | | ---------------------- | --------------------------------------------------------------------------------------- | | [GET](#211-get-method) | Fetch Session object of charging sessions started between the {date_from} and {date_to} ([paginated](transport_and_format.md#get)) | | POST | n/a | | PUT | n/a | | PATCH | n/a | | DELETE | n/a |

2.1.1 GET Method

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.

Response Data

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 |

2.2 eMSP Interface

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}

| Method | Description | |------------------------------|---------------------------------------------------------------------| | [GET](#221-get-method) | Get the Session object from the eMSP system by its id {session-id}. | | POST | n/a | | [PUT](#222-put-method) | Send a new/updated Session object | | [PATCH](#223-patch-method) | Update the Session object of id {session-id}. | | [DELETE](#224-delete-method) | Delete the Session object of id {session-id}. |

2.2.1 GET Method

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.

Request Parameters
| 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. |
Response Data

The response contains the request Session object, if available.

| Datatype | Card. | Description | |-------------------------------|-------|---------------------------------------------------------------| | [Session](#31-session-object) | 1 | Session object requested. |

2.2.2 PUT Method

Inform the system about a new/updated session in the eMSP backoffice by PUTing a Session object.

Request Body

The request contains the new or updated Session object.

| Type | Card. | Description | |---------------------------------|-------|------------------------------------------| | [Session](#31-session-object) | 1 | new Session object. |
Request Parameters
| 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. |

2.2.3 PATCH Method

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.

Example: update the total cost
PATCH To URL: https://www.server.com/ocpi/cpo/2.0/sessions/NL/TNM/101

{
  	"total_cost": "0.60"
}

2.2.4 DELETE Method

Inform the eMSP about a deleted Session object.

Request Parameters
| 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 |

3. Object description

3.1 Session Object

| 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. |

Examples

Simple Session example of a just starting 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"
}
Simple Session example of a short finished session
{
	"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"
}

4. Data types

Describe all datatypes used in this object

4.1 SessionStatus enum

| 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. |