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 send 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 ASAP. But if there is an agreement between parties to send then for example once a month, that is also allowed by OCPI.
CDRs are created by the CPO. They are probably only send 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 send to the eMSP, changes are not allowed in a CDR.
When the CPO creates CDR(s) they push them to the relevant eMSP by calling POST on the eMSPs CDRs endpoint with the newly create CDRs(s)
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 might calculate its own costs for billing their customer. An eMSP might have a very different contract/pricing model with the EV driver then the tariff structure from the CPO.
NOTE: CDRs cannot 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.
eMSPs who do not support the push model need to call GET on the CPOs CDRs endpoint to receive a list of CDRs.
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.
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
Fetch CDRs from the CPO systems.
If additional parameters: {date_from} and/or {date_to} are provided, only CDRs of charging sessions with a start date/time 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](types.md#12_datetime_type) | no | Begin charging session start Date/Time of CDRs to fetch. | | date_to | [DateTime](types.md#12_datetime_type) | no | End charging session start Date/Time of CDRs to fetch, if omitted all CDRs 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. |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](#31-cdr-object) | * | List of CDRs. |The CDRs endpoint can be used to create, or get CDRs.
Example endpoint structure: /ocpi/emsp/2.0/cdrs
Fetch CDRs from the eMSP system.
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.
The endpoint returns the requested CDR, if it exists
| Datatype | Card. | Description | |-----------------------|-------|----------------------------------------------| | [CDR](#31-cdr-object) | 1 | Requested CDR object. |Creates a new CDR.
The post method should contain the full, final CDR object.
In the post request the new CDR object is send.
| Type | Card. | Description | |---------------------------------|-------|-----------------------------------------| | [CDR](#31-cdr-object) | 1 | New CDR object. | | Parameter | Datatype | Required | Description | |------------|-----------------------------|----------|-------------------------------------------| | Location | [URL](types.md#14_url_type) | 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
The CDR object describes the Charging Session and its costs. How these costs are build up etc.
| Property | Type | Card. | Description | |--------------------------------------|----------------------------------------------------------|-------|--------------------------------------------------------------------------------------------------------------------------------| | id | [CiString](types.md#12-cistring-type)(15) | 1 | Uniquely identifies the CDR within the CPOs platform (and suboperator platforms). | | start_date_time | [DateTime](types.md#12-datetime-type) | 1 | Start timestamp of the charging session. | | stop_date_time | [DateTime](types.md#12-datetime-type) | ? | Stop timestamp of the charging session. | | auth_id | [string](types.md#16-string-type)(32) | 1 | Reference to a token, identified by the auth_id field of the [Token](mod_tokens.md#31_token_object). | | auth_method | [AuthMethod](#41-authmethod-enum) | 1 | Method used for authentication. | | location | [Location](mod_locations.md#31-location-object) | 1 | Location were the charging session took place, including only the relevant [EVSE](mod_locations.md#32-evse-object) and [Connector](mod_locations.md#33-connector-object). | | meter_id | [string](types.md#16-string-type)(255) | ? | Identification of the Meter inside the Charge Point. | | currency | [string](types.md#16-string-type)(3) | 1 | Currency of the CDR in ISO 4217 Code. | | tariffs | [Tariff](mod_tariffs.md#31-tariff-object) | * | List of relevant tariff elements, see: [Tariffs](mod_tariffs.md#31-tariff-object). | | charging_periods | [ChargingPeriod](#43-chargingperiod-class) | + | List of charging periods that make up this charging session. A session consist of 1 or more periodes with, each period has a different relevant Tariff. | | total_cost | [decimal](types.md#13-decimal-type) | 1 | Total cost of this transaction. | | total_usage | [CdrDimension](#42-cdrdimension-class) | * | List of total usage elements, for example: total parking time and total energy charged. | | remark | [string](types.md#16-string-type)(255) | ? | Optional remark, can be used to provide addition human readable information to the CDR, for example: reason why a transaction was stopped.|{
"id": "12345",
"start_date_time": "2015-06-29T21:39:09+02:00",
"stop_date_time": "2015-06-29T23:37:32+02:00",
"auth_id": "FA54320",
"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.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",
"tariffs": [{
"id": "12",
"currency": "EUR",
"elements": [{
"price_components": [{
"type": "TIME",
"price": "2.00",
"step_size": 300
}]
}]
}],
"charging_periods": [{
"start_date_time": "2015-06-29T21:39:09+02:00",
"dimensions": [{
"type": "TIME",
"volume": "1.973"
}]
}],
"total_cost": "4,00",
"total_usage": [{
"type": "TIME",
"volume": "1.973"
}, {
"type": "ENERGY",
"volume": "15.342"
}]
}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](types.md#12-datetime-type) | 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](#42-cdrdimension-class) | + | List of relevant values for this charging period. |