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

<div><!-- ---------------------------------------------------------------------------- --></div>

<!-- 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: {date_from} and/or {date_to} 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.

<div><!-- ---------------------------------------------------------------------------- --></div>

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.

<div><!-- ---------------------------------------------------------------------------- --></div>

2.2 eMSP Interface

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

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

<div><!-- ---------------------------------------------------------------------------- --></div>

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

<div><!-- ---------------------------------------------------------------------------- --></div>

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.

<div><!-- ---------------------------------------------------------------------------- --></div>

Response Headers

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

<div><!-- ---------------------------------------------------------------------------- --></div>

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.

<div><!-- ---------------------------------------------------------------------------- --></div>

NOTE: 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

<div><!-- ---------------------------------------------------------------------------- --></div>

4.2 CdrDimension class

<div><!-- ---------------------------------------------------------------------------- --></div>

4.3 CdrDimensionType enum

<div><!-- ---------------------------------------------------------------------------- --></div>

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.

<div><!-- -------------------------------------------------------------------------------- --></div>

5. Schema & Examples

Below are the JSON Schemas and example payloads for this module, embedded inline.

Schemas

Examples