API docs by Redocly

OCPI 2.3.0 - Sessions Module - Receiver Interface (2.3.0)

Download OpenAPI specification:

URL: https://evroaming.org

The Receiver Interface is typically implemented by market roles like the eMSP and SCSP. This interface allows senders (CPOs) to push Session data.

Sessions are Client Owned Objects, so the endpoints need to contain the required extra fields: {country_code}/{party_id}/{session_id}.

Endpoint structure definition: {sessions_endpoint_url}/{country_code}/{party_id}/{session_id}

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"
}

SessionPatch

start_date_time
string <date-time>
end_date_time
string <date-time>
kwh
number
object (CdrToken)

Token information used to start a charging session, containing all relevant information to identify the unique token.

auth_method
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.

authorization_reference
string <= 36 characters
location_id
string <= 36 characters
evse_uid
string <= 36 characters
connector_id
string <= 36 characters
meter_id
string <= 255 characters
currency
string = 3 characters
Array of objects (ChargingPeriod)

When present in a PATCH, these ChargingPeriod objects are added to the existing list.

object (Price)

Price information with tax details.

status
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.

last_updated
required
string <date-time>
{
  • "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"
}

Sessions

Get a Session

The CPO system might request the current version of a Session object from the eMSP's system to, for example, validate the state, or because the CPO has received an error during a PATCH operation.

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

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

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.

Responses

Response samples

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

Create or replace a Session

Inform the eMSP's system about a new/updated Session object in the CPO's system.

When a PUT request is received for an existing Session object (the object is PUT to the same URL), the newly received Session object SHALL replace the existing object.

Any charging_periods from the existing object SHALL be replaced by the charging_periods from the newly received Session object. If the new Session object does not contain charging_periods (field is omitted or contains an empty list), the charging_periods of the existing object SHALL be removed (replaced by the new empty list).

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO performing this PUT on the eMSP’s system. This SHALL be the same value as the country_code in the Session object being pushed.

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO performing this PUT on the eMSP’s system. This SHALL be the same value as the party_id in the Session object being pushed.

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

New or updated Session object.

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).

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Partially update a Session

Same as the PUT method, but only the fields/objects that need to be updated have to be present. Fields/objects which are not specified are considered unchanged.

Any request to the PATCH method SHALL contain the last_updated field.

The PATCH method works on the entire Session object only. It is not allowed to use extra URL segments to try to PATCH fields of inner objects of the Session object directly.

When a PATCH request contains the charging_periods field (inside a Session object), this SHALL be processed as a request to add all the ChargingPeriod objects to the existing Session object. If the request charging_periods list is omitted (or contains an empty list), no changes SHALL be made to the existing list of charging_periods.

If existing ChargingPeriod objects in a Session need to be replaced or removed, the Sender SHALL use the PUT method to replace the entire Session object (including all the charging_periods).

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

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

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

The partial Session object containing only the fields to update. Must contain last_updated.

start_date_time
string <date-time>
end_date_time
string <date-time>
kwh
number
object (CdrToken)

Token information used to start a charging session, containing all relevant information to identify the unique token.

auth_method
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.

authorization_reference
string <= 36 characters
location_id
string <= 36 characters
evse_uid
string <= 36 characters
connector_id
string <= 36 characters
meter_id
string <= 255 characters
currency
string = 3 characters
Array of objects (ChargingPeriod)

When present in a PATCH, these ChargingPeriod objects are added to the existing list.

object (Price)

Price information with tax details.

status
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.

last_updated
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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