API docs by Redocly

OCPI 2.3.0 - Sessions Module - Sender Interface (2.3.0)

Download OpenAPI specification:

URL: https://evroaming.org

The Sender Interface is typically implemented by market roles like the CPO. This interface allows receivers (eMSPs) to fetch Session data and set Charging Preferences.

The Sender interface provides two functionalities:

  • GET: Fetch a list of Sessions, optionally filtered on last_updated.
  • PUT: Set/update the driver's Charging Preferences for an ongoing session.
OCPI 2.3.0 Specification

Schemas

OCPIResponse

status_code
required
integer

OCPI status code, 1000 for success.

status_message
string

An optional status message which may help when debugging.

timestamp
required
string <date-time>

The time this message was generated.

data
any

Response data object or list of objects.

{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}

TokenType

string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

The type of token.

"AD_HOC_USER"

CdrToken

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the MSP that 'owns' this Token.

party_id
required
string = 3 characters

ID of the eMSP that 'owns' this Token (following the ISO-15118 standard).

uid
required
string <= 36 characters

Unique ID by which this Token can be identified. This is the field used by the CPO's system (RFID reader on the Charge Point) to identify this token. Currently, in most cases: type=RFID, this is the RFID hidden ID as read by the RFID reader, but that is not a requirement. If this is a type=APP_USER Token, it will be a unique, by the eMSP, generated ID.

type
required
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Type of the token

contract_id
required
string <= 36 characters

Uniquely identifies the EV Driver contract token within the eMSP's platform (and suboperator platforms). Recommended to follow the specification for eMA ID from "E-mobility ID-codes: the purpose of IDs, ID usage and ID format" (https://evroaming.org/contract-evse-ids/).

{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string"
}

AuthMethod

string <enum> (AuthMethod)
Enum Description
AUTH_REQUEST

Authentication request has been sent to the eMSP.

COMMAND

Command like StartSession or ReserveNow used to start the Session, the Token provided in the Command was used as authorization.

WHITELIST

Whitelist used for authentication, no request to the eMSP has been performed.

Method used for authentication.

"AUTH_REQUEST"

CdrDimensionType

string <enum> (CdrDimensionType)
Enum Description
CURRENT

(Session Only) Average charging current during this ChargingPeriod: defined in A (Ampere). When negative, the current is flowing from the EV to the grid.

ENERGY

Total amount of energy (dis-)charged during this ChargingPeriod: defined in kWh. When negative, more energy was fed into the grid than charged into the EV. Default step_size is 1.

ENERGY_EXPORT

(Session Only) Total amount of energy fed back into the grid: defined in kWh.

ENERGY_IMPORT

(Session Only) Total amount of energy charged, defined in kWh.

MAX_CURRENT

Sum of the maximum current over all phases, reached during this ChargingPeriod: defined in A (Ampere).

MIN_CURRENT

Sum of the minimum current over all phases, reached during this ChargingPeriod, when negative, current has flowed from the EV to the grid. Defined in A (Ampere).

MAX_POWER

Maximum power reached during this ChargingPeriod: defined in kW (Kilowatt).

MIN_POWER

Minimum power reached during this ChargingPeriod: defined in kW (Kilowatt), when negative, the power has flowed from the EV to the grid.

PARKING_TIME

Time during this ChargingPeriod not charging: defined in hours, default step_size multiplier is 1 second.

POWER

(Session Only) Average power during this ChargingPeriod: defined in kW (Kilowatt). When negative, the power is flowing from the EV to the grid.

RESERVATION_TIME

Time during this ChargingPeriod the Charge Point has been reserved time, defined in hours default step_size multiplier is 1 second.

RESERVATION_EXPIRES

Time during this ChargingPeriod Charge Point has been reserved and not yet been in use for this customer: defined in hours, default step_size multiplier is 1 second.

RESERVATION_OVERTIME

Time after the reservation during a ChargingPeriod that the session continues after the reserved time slot, defined in hours, default step_size multiplier is 1 second.

STATE_OF_CHARGE

(Session Only) Current state of charge of the EV, in percentage, values allowed: 0 to 100.

TIME

Time charging during this ChargingPeriod: defined in hours, default step_size multiplier is 1 second.

Defines the type of a CDR dimension. Some of these values are not useful for CDRs, and SHALL therefore only be used in Sessions (marked as Session Only).

"CURRENT"

CdrDimension

type
required
string <enum> (CdrDimensionType)
Enum Description
CURRENT

(Session Only) Average charging current during this ChargingPeriod: defined in A (Ampere). When negative, the current is flowing from the EV to the grid.

ENERGY

Total amount of energy (dis-)charged during this ChargingPeriod: defined in kWh. When negative, more energy was fed into the grid than charged into the EV. Default step_size is 1.

ENERGY_EXPORT

(Session Only) Total amount of energy fed back into the grid: defined in kWh.

ENERGY_IMPORT

(Session Only) Total amount of energy charged, defined in kWh.

MAX_CURRENT

Sum of the maximum current over all phases, reached during this ChargingPeriod: defined in A (Ampere).

MIN_CURRENT

Sum of the minimum current over all phases, reached during this ChargingPeriod, when negative, current has flowed from the EV to the grid. Defined in A (Ampere).

MAX_POWER

Maximum power reached during this ChargingPeriod: defined in kW (Kilowatt).

MIN_POWER

Minimum power reached during this ChargingPeriod: defined in kW (Kilowatt), when negative, the power has flowed from the EV to the grid.

PARKING_TIME

Time during this ChargingPeriod not charging: defined in hours, default step_size multiplier is 1 second.

POWER

(Session Only) Average power during this ChargingPeriod: defined in kW (Kilowatt). When negative, the power is flowing from the EV to the grid.

RESERVATION_TIME

Time during this ChargingPeriod the Charge Point has been reserved time, defined in hours default step_size multiplier is 1 second.

RESERVATION_EXPIRES

Time during this ChargingPeriod Charge Point has been reserved and not yet been in use for this customer: defined in hours, default step_size multiplier is 1 second.

RESERVATION_OVERTIME

Time after the reservation during a ChargingPeriod that the session continues after the reserved time slot, defined in hours, default step_size multiplier is 1 second.

STATE_OF_CHARGE

(Session Only) Current state of charge of the EV, in percentage, values allowed: 0 to 100.

TIME

Time charging during this ChargingPeriod: defined in hours, default step_size multiplier is 1 second.

Type of CDR dimension.

volume
required
number

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

{
  • "type": "CURRENT",
  • "volume": 0
}

ChargingPeriod

start_date_time
required
string <date-time>

Start timestamp of the charging period. A period ends when the next period starts. The last period ends when the session ends.

required
Array of objects (CdrDimension) non-empty

List of relevant values for this charging period.

tariff_id
string <= 36 characters

Unique identifier of the Tariff that is relevant for this Charging Period. If not provided, no Tariff is relevant during this period.

{
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "dimensions": [
    ],
  • "tariff_id": "string"
}

TaxAmount

name
required
string

A description of the tax. In countries where a tax name is required like Canada this can be something like "QST". In countries where this is not required, this can be something more generic like "VAT" or "General Sales Tax".

account_number
string

Tax Account Number of the business entity remitting these taxes. Optional as this is not required in all countries.

percentage
number

Tax percentage. Optional as this is not required in all countries.

amount
required
number

The amount of money of this tax that is due.

{
  • "name": "string",
  • "account_number": "string",
  • "percentage": 0,
  • "amount": 0
}

Price

before_taxes
required
number

Price/Cost excluding taxes.

Array of objects (TaxAmount)

All taxes that are applicable to this price and relevant to the receiver of the Session or CDR.

{
  • "before_taxes": 0,
  • "taxes": [
    ]
}

SessionStatus

string <enum> (SessionStatus)
Enum Description
ACTIVE

The session has been accepted and is active. All pre-conditions were met: Communication between EV and EVSE (for example: cable plugged in correctly), EV or driver is authorized. EV is being charged, or can be charged. Energy is, or is not, being transfered.

COMPLETED

The session has been finished successfully. No more modifications will be made to the Session object using this state.

INVALID

The Session object using this state is declared invalid and will not be billed.

PENDING

The session is pending, it has not yet started. Not all pre-conditions are met. This is the initial state. The session might never become an active session.

RESERVATION

The session is started due to a reservation, charging has not yet started. The session might never become an active session.

Defines the state of a session.

"ACTIVE"

Session

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the CPO that 'owns' this Session.

party_id
required
string = 3 characters

ID of the CPO that 'owns' this Session (following the ISO-15118 standard).

id
required
string <= 36 characters

The unique id that identifies the charging session in the CPO platform.

start_date_time
required
string <date-time>

The timestamp when the session became ACTIVE in the Charge Point. When the session is still PENDING, this field SHALL be set to the time the Session was created at the Charge Point. When a Session goes from PENDING to ACTIVE, this field SHALL be updated to the moment the Session went to ACTIVE in the Charge Point.

end_date_time
string <date-time>

The timestamp when the session was completed/finished, charging might have finished before the session ends, for example: EV is full, but parking cost also has to be paid.

kwh
required
number

How many kWh were charged.

required
object (CdrToken)

Token used to start this charging session, including all the relevant information to identify the unique token.

auth_method
required
string <enum> (AuthMethod)
Enum Description
AUTH_REQUEST

Authentication request has been sent to the eMSP.

COMMAND

Command like StartSession or ReserveNow used to start the Session, the Token provided in the Command was used as authorization.

WHITELIST

Whitelist used for authentication, no request to the eMSP has been performed.

Method used for authentication. This might change during a session, for example when the session was started with a reservation: ReserveNow: COMMAND. When the driver arrives and starts charging using a Token that is whitelisted: WHITELIST.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP. When the eMSP provided an authorization_reference in either: real-time authorization, StartSession or ReserveNow this field SHALL contain the same value. When different authorization_reference values have been given by the eMSP that are relevant to this Session, the last given value SHALL be used here.

location_id
required
string <= 36 characters

Location.id of the Location object of this CPO, on which the charging session is/was happening.

evse_uid
required
string <= 36 characters

EVSE.uid of the EVSE of this Location on which the charging session is/was happening. Allowed to be set to: #NA when this session is created for a reservation, but no EVSE yet assigned to the driver.

connector_id
required
string <= 36 characters

Connector.id of the Connector of this Location where the charging session is/was happening. Allowed to be set to: #NA when this session is created for a reservation, but no connector yet assigned to the driver.

meter_id
string <= 255 characters

Optional identification of the kWh meter.

currency
required
string = 3 characters

ISO 4217 code of the currency used for this session.

Array of objects (ChargingPeriod)

An optional list of Charging Periods that can be used to calculate and verify the total cost.

object (Price)

The total cost of the session in the specified currency. This is the price that the eMSP will have to pay to the CPO. A total_cost of 0.00 means free of charge. When omitted, i.e. no price information is given in the Session object, it does not imply the session is/was free of charge.

status
required
string <enum> (SessionStatus)
Enum Description
ACTIVE

The session has been accepted and is active. All pre-conditions were met: Communication between EV and EVSE (for example: cable plugged in correctly), EV or driver is authorized. EV is being charged, or can be charged. Energy is, or is not, being transfered.

COMPLETED

The session has been finished successfully. No more modifications will be made to the Session object using this state.

INVALID

The Session object using this state is declared invalid and will not be billed.

PENDING

The session is pending, it has not yet started. Not all pre-conditions are met. This is the initial state. The session might never become an active session.

RESERVATION

The session is started due to a reservation, charging has not yet started. The session might never become an active session.

The status of the session.

last_updated
required
string <date-time>

Timestamp when this Session was last updated (or created).

{
  • "country_code": "st",
  • "party_id": "str",
  • "id": "string",
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "end_date_time": "2019-08-24T14:15:22Z",
  • "kwh": 0,
  • "cdr_token": {
    },
  • "auth_method": "AUTH_REQUEST",
  • "authorization_reference": "string",
  • "location_id": "string",
  • "evse_uid": "string",
  • "connector_id": "string",
  • "meter_id": "string",
  • "currency": "str",
  • "charging_periods": [
    ],
  • "total_cost": {
    },
  • "status": "ACTIVE",
  • "last_updated": "2019-08-24T14:15:22Z"
}

ProfileType

string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Different smart charging profile types.

"CHEAP"

ChargingPreferences

profile_type
required
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Type of Smart Charging Profile selected by the driver. The ProfileType has to be supported at the Connector and for every supported ProfileType, a Tariff MUST be provided. This gives the EV driver the option between different pricing options.

departure_time
string <date-time>

Expected departure. The driver has given this Date/Time as expected departure moment. It is only an estimation and not necessarily the Date/Time of the actual departure.

energy_need
number

Requested amount of energy in kWh. The EV driver wants to have this amount of energy charged.

discharge_allowed
boolean

The driver allows their EV to be discharged when needed, as long as the other preferences are met: EV is charged with the preferred energy (energy_need) until the preferred departure moment (departure_time). Default if omitted: false.

{
  • "profile_type": "CHEAP",
  • "departure_time": "2019-08-24T14:15:22Z",
  • "energy_need": 0,
  • "discharge_allowed": true
}

ChargingPreferencesResponse

string <enum> (ChargingPreferencesResponse)
Enum Description
ACCEPTED

Charging Preferences accepted, EVSE will try to accomplish them, although this is no guarantee that they will be fulfilled.

DEPARTURE_REQUIRED

CPO requires departure_time to be able to perform Charging Preference based Smart Charging.

ENERGY_NEED_REQUIRED

CPO requires energy_need to be able to perform Charging Preference based Smart Charging.

NOT_POSSIBLE

Charging Preferences contain a demand that the EVSE knows it cannot fulfill.

PROFILE_TYPE_NOT_SUPPORTED

profile_type contains a value that is not supported by the EVSE.

An enum with possible responses to a PUT Charging Preferences request.

"ACCEPTED"

Sessions

Get list of Sessions

Fetch a list of Sessions from the CPO system (paginated).

Only Sessions with last_updated between the given date_from (including) and date_to (excluding) will be returned.

Authorizations:
ocpiAuthorization
query Parameters
date_from
string <date-time>

Only return objects that have last_updated after or equal to this Date/Time (inclusive).

date_to
string <date-time>

Only return objects that have last_updated up to this Date/Time, but not including (exclusive).

limit
integer >= 1

Maximum number of objects to GET.

offset
integer >= 0
Default: 0

The offset of the first object returned. Default is 0.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": [
    ]
}

Set Charging Preferences

Set/update the driver's Charging Preferences for this charging session.

The /charging_preferences URL suffix is required when setting Charging Preferences.

Authorizations:
ocpiAuthorization
path Parameters
session_id
required
string <= 36 characters

Session.id of the Session object.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required

Updated Charging Preferences of the driver for this Session.

profile_type
required
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Type of Smart Charging Profile selected by the driver. The ProfileType has to be supported at the Connector and for every supported ProfileType, a Tariff MUST be provided. This gives the EV driver the option between different pricing options.

departure_time
string <date-time>

Expected departure. The driver has given this Date/Time as expected departure moment. It is only an estimation and not necessarily the Date/Time of the actual departure.

energy_need
number

Requested amount of energy in kWh. The EV driver wants to have this amount of energy charged.

discharge_allowed
boolean

The driver allows their EV to be discharged when needed, as long as the other preferences are met: EV is charged with the preferred energy (energy_need) until the preferred departure moment (departure_time). Default if omitted: false.

Responses

Request samples

Content type
application/json
{
  • "profile_type": "CHEAP",
  • "departure_time": "2019-08-24T14:15:22Z",
  • "energy_need": 0,
  • "discharge_allowed": true
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": "ACCEPTED"
}