Cdrs

CDRs module

Module Identifier: cdrs

A Charge Detail Record is the description of a concluded charging session. The CDR is the only billing-relevant object. CDRs are sent from the CPO to the eMSP after the charging session has ended. There is no requirement to send CDRs semi-realtime, it is seen as good practice to send them as soon as possible. But if there is an agreement between parties to send them for example once a month, that is also allowed by OCPI.

1. Flow and Lifecycle

CDRs are created by the CPO. They probably only will be sent to the eMSP that will be paying the bill of a charging session. Because a CDR is for billing purposes, it cannot be changed/replaced, once sent to the eMSP, changes are not allowed in a CDR.

1.1 Push model

When the CPO creates CDR(s) they push them to the relevant eMSP by calling POST on the eMSPs CDRs endpoint with the newly created CDR(s). A CPO is not required to send ALL CDRs to ALL eMSPs, it is allowed to only send CDRs to the eMSP that a CDR is relevant to.

CDRs should contain enough information (dimensions) to allow the eMSP to validate the total costs. It is advised to send enough information to the eMSP so it can calculate its own costs for billing their customer. An eMSP might have a very different contract/pricing model with the EV driver than the tariff structure from the CPO.

NOTE: CDRs can not yet be updated or removed. This might be added in a future version of OCPI.

If the CPO, for any reason wants to view a CDR it has posted to a eMSP system, the CPO can retrieve the CDR by calling the GET on the eMSPs CDRs endpoint at the URL returned in the response to the POST.

1.2 Pull model

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

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

A CPO is not required to return all known CDRs, the CPO is allowed to return only the CDRs that are relevant for the requesting eMSP.

2. Interfaces and endpoints

There is both a CPO and an eMSP interface for CDRs. Depending on business requirements parties can decide to use the CPO Interface/Get model, or the eMSP Interface/Push model, or both. Push is the preferred model to use, the eMSP will receive CDRs when created by the CPO.

2.1 CPO Interface

The CDRs endpoint can be used to create or retrieve CDRs.

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

Method

Description

GET

Fetch CDRs, last updated (which in the current version of OCPI can only be the creation date/time) between the and (paginated)

POST

n/a

PUT

n/a

PATCH

n/a

DELETE

n/a

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

2.1.1 GET Method

Fetch CDRs from the CPO systems.

Request Parameters

If additional parameters: and/or are provided, only CDRs with last_updated between the given date_from and date_to will be returned.

This request is paginated, it supports the pagination related URL parameters.

Parameter

Datatype

Required

Description

date_from

DateTime

no

Only return CDRs that have last_updated after this Date/Time.

date_to

DateTime

no

Only return CDRs 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 endpoint returns a list of CDRs matching the given parameters in the GET 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

CDR

*

List of CDRs.

2.2 eMSP Interface

The CDRs endpoint can be used to create, or get CDRs.

Example endpoint structure: /ocpi/emsp/2.0/cdrs

Method

Description

GET

Retrieve an existing CDR

POST

Send a new CDR.

PUT

n/a (CDRs cannot be replaced)

PATCH

n/a (CDRs cannot be updated)

DELETE

n/a (CDRs cannot be removed)
2.2.1 GET Method

Fetch CDRs from the eMSP system.

Response URL

To retrieve an existing URL from the eMSP system, the URL, returned in the response to a POST of a new CDR, has to be used.

Response Data

The endpoint returns the requested CDR, if it exists

Datatype

Card.

Description

CDR

1

Requested CDR object.
2.2.2 POST Method

Creates a new CDR.

The post method should contain the full, final CDR object.

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

Request Body

In the post request the new CDR object is sent.

Type

Card.

Description

CDR

1

New CDR object.
Response Headers

The response should contain the URL to the just created CDR object in the eMSP system.

HTTP Header

Datatype

Required

Description

Location

URL

yes

URL to the newly created CDR in the eMSP system, can be used by the CPO system to do a GET on of the same CDR

Example: Location: /ocpi/emsp/2.0/cdrs/123456

3. Object description

3.1 CDR Object

The CDR object describes the Charging Session and its costs, how these costs are built up, etc.

Property

Type

Card.

Description

id

CiString(36)

1

Uniquely identifies the CDR within the CPOs platform (and suboperator platforms).

start_date_time

DateTime

1

Start timestamp of the charging session.

stop_date_time

DateTime

1

Stop timestamp of the charging session.

auth_id

string(36)

1

Reference to a token, identified by the auth_id field of the Token.

auth_method

AuthMethod

1

Method used for authentication.

location

Location

1

Location where the charging session took place, including only the relevant EVSE and Connector.

meter_id

string(255)

?

Identification of the Meter inside the Charge Point.

currency

string(3)

1

Currency of the CDR in ISO 4217 Code.

tariffs

Tariff

*

List of relevant tariff elements, see: Tariffs. When relevant, a "Free of Charge" tariff should also be in this list, and point to a defined "Free of Charge" tariff.

charging_periods

ChargingPeriod

+

List of charging periods that make up this charging session. A session consists of 1 or more periods, where each period has a different relevant Tariff.

total_cost

number

1

Total cost (excluding VAT) of this transaction.

total_energy

number

1

Total energy charged, in kWh.

total_time

number

1

total duration of this session (including the duration of charging and not charging), in hours.

total_parking_time

number

?

Total duration during this session that the EV is not being charged (no energy being transfered between EVSE and EV), in hours.

remark

string(255)

?

Optional remark, can be used to provide addition human readable information to the CDR, for example: reason why a transaction was stopped.

last_updated

DateTime

1

Timestamp when this CDR was last updated (or created).
The duration of charging (energy being transferred between EVSE and EV) during this session can be calculated via: total_time - total_parking_time.

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

Example of a CDR
{
	"id": "12345",
	"start_date_time": "2015-06-29T21:39:09Z",
	"stop_date_time": "2015-06-29T23:37:32Z",
	"auth_id": "DE8ACC12E46L89",
	"auth_method": "WHITELIST",
	"location": {
		"id": "LOC1",
		"type": "ON_STREET",
		"name": "Gent Zuid",
		"address": "F.Rooseveltlaan 3A",
		"city": "Gent",
		"postal_code": "9000",
		"country": "BE",
		"coordinates": {
			"latitude": "3.729944",
			"longitude": "51.047599"
		},
		"evses": [{
			"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",
				"last_updated": "2015-06-29T21:39:01Z"
			}],
			"last_updated": "2015-06-29T21:39:01Z"
		}],
		"last_updated": "2015-06-29T21:39:01Z"
	},
	"currency": "EUR",
	"tariffs": [{
		"id": "12",
		"currency": "EUR",
		"elements": [{
			"price_components": [{
				"type": "TIME",
				"price": "2.00",
				"step_size": 300
			}]
		}],
		"last_updated": "2015-02-02T14:15:01Z"
	}],
	"charging_periods": [{
		"start_date_time": "2015-06-29T21:39:09Z",
		"dimensions": [{
			"type": "TIME",
			"volume": 1.973
		}]
	}],
	"total_cost": 4.00,
	"total_energy": 15.342,
	"total_time": 1.973,
	"last_updated": "2015-06-29T22:01:13Z"
}

4. Data types

4.1 AuthMethod enum

Value

Description

AUTH_REQUEST

Authentication request from the eMSP

WHITELIST

Whitelist used to authenticate, no request done to the eMSP

4.2 CdrDimension class

Property

Type

Card.

Description

type

CdrDimensionType

1

Type of cdr dimension

volume

number

1

Volume of the dimension consumed, measured according to the dimension type.

4.3 CdrDimensionType enum

Value

Description

ENERGY

defined in kWh, default step_size is 1 Wh

FLAT

flat fee, no unit

MAX_CURRENT

defined in A (Ampere), Maximum current reached during charging session

MIN_CURRENT

defined in A (Ampere), Minimum current used during charging session

PARKING_TIME

time not charging: defined in hours, default step_size is 1 second

TIME

time charging: defined in hours, default step_size is 1 second

4.4 ChargingPeriod class

A charging period consists of a start timestamp and a list of possible values that influence this period, for example: Amount of energy charged this period, maximum current during this period etc.

Property

Type

Card.

Description

start_date_time

DateTime

1

Start timestamp of the charging period. This period ends when a next period starts, the last period ends when the session ends.

dimensions

CdrDimension

+

List of relevant values for this charging period.