Skip to content

Latest commit

 

History

History
311 lines (241 loc) · 16.2 KB

mod_sessions.md

File metadata and controls

311 lines (241 loc) · 16.2 KB
Raw

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 pushed 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 sent to the eMSP system by calling PATCH on the eMSPs 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 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.

This GET can also be used, combined with the Push model to retrieve Sessions after the system (re)connects to a CPO, to get a list Sessions 'missed' during a time offline.

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 objects of charging sessions last updated 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.

Request Parameters

Only Sessions with last_update 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 | Only return Sessions that have `last_updated` after this Date/Time. | | date_to | [DateTime](types.md#12-datetime-type) | no | Only return Sessions that have `last_updated` before this Date/Time. | | offset | int | no | The offset of the first object returned. Default is 0. | | limit | int | no | Maximum number of objects to GET. |
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}/{session_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 | n/a |

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

The following parameters can be provided as URL segments.

| Parameter | Datatype | Required | Description | |------------------|---------------------------------------|----------|-------------------------------------------------------------------------------| | country_code | [string](types.md#15-string-type)(2) | yes | Country code of the CPO requesting this PUT to the eMSP system. | | party_id | [string](types.md#15-string-type)(3) | yes | Party ID (Provider ID) of the CPO requesting this PUT to the eMSP system. | | session_id | [string](types.md#15-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

The following parameters can be provided as URL segments.

| Parameter | Datatype | Required | Description | |------------------|---------------------------------------|----------|-------------------------------------------------------------------------------| | country_code | [string](types.md#15-string-type)(2) | yes | Country code of the CPO requesting this PUT to the eMSP system. | | party_id | [string](types.md#15-string-type)(3) | yes | Party ID (Provider ID) of the CPO requesting this PUT to the eMSP system. | | session_id | [string](types.md#15-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"
}

3. Object description

3.1 Session Object

| Property | Type | Card. | Description | |-----------------------------------|------------------------------------------------------------|-------|----------------------------------------------------------------------------------------------------------------| | id | [string](types.md#15-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 | [number](types.md#14-number-type) | 1 | How many kWh are charged. | | auth_id | [string](types.md#15-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#15-string-type)(255) | ? | Optional identification of the kWh meter. | | currency | [string](types.md#15-string-type)(3) | 1 | ISO 4217 code of the currency used for this session. | | charging_periods | [ChargingPeriod](mod_cdrs.md#44-chargingperiod-class) | * | An optional list of charging periods that can be used to calculate and verify the total cost. | | total_cost | [number](types.md#14-number-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. | | last_updated | [DateTime](types.md#12-datetime-type) | 1 | Timestamp when this Session was last updated. |

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"
			}]
		}
	},
	"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 is 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. |