API docs by Redocly

OCPI 2.3.0 - Commands Module - Receiver Interface (2.3.0)

Download OpenAPI specification:

URL: https://evroaming.org

The Receiver Interface (typically implemented by the CPO) allows the Sender (eMSP) to send commands to the CPO, such as StartSession, StopSession, ReserveNow, CancelReservation and UnlockConnector.

OCPI 2.3.0 Specification

Schemas

CancelReservation

response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between CancelReservation requests.

reservation_id
required
string <= 36 characters

Reservation id, unique for this reservation. If the Charge Point already has a reservation that matches this reservationId the Charge Point will replace the reservation.

{}

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
}

CommandResponseType

string <enum> (CommandResponseType)
Enum Description
NOT_SUPPORTED

The requested command is not supported by this CPO, Charge Point, EVSE etc.

REJECTED

Command request rejected by the CPO. (Session might not be from a customer of the eMSP that sent this request)

ACCEPTED

Command request accepted by the CPO.

UNKNOWN_SESSION

The Session in the requested command is not known by this CPO.

Response to the command request from the eMSP to the CPO.

"NOT_SUPPORTED"

DisplayText

language
required
string = 2 characters

Language Code ISO 639-1.

text
required
string <= 512 characters

Text to be displayed to an end user. No markup, html etc. allowed.

{
  • "language": "st",
  • "text": "string"
}

CommandResponse

result
required
string <enum> (CommandResponseType)
Enum Description
NOT_SUPPORTED

The requested command is not supported by this CPO, Charge Point, EVSE etc.

REJECTED

Command request rejected by the CPO. (Session might not be from a customer of the eMSP that sent this request)

ACCEPTED

Command request accepted by the CPO.

UNKNOWN_SESSION

The Session in the requested command is not known by this CPO.

Response from the CPO on the command request.

timeout
required
integer

Timeout for this command in seconds. When the Result is not received within this timeout, the eMSP can assume that the message might never be sent.

Array of objects (DisplayText)

Human-readable description of the result (if one can be provided), multiple languages can be provided.

{
  • "result": "NOT_SUPPORTED",
  • "timeout": 0,
  • "message": [
    ]
}

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"

WhitelistType

string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Defines when authorization of a Token by the CPO is allowed.

"ALWAYS"

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"

EnergyContract

supplier_name
required
string <= 64 characters

Name of the energy supplier for this token.

contract_id
string <= 64 characters

Contract ID at the energy supplier, that belongs to the owner of this token.

{
  • "supplier_name": "string",
  • "contract_id": "string"
}

Token

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, combined with the Token type, can be identified. This is the field used by CPO 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 APP_USER or AD_HOC_USER Token, it will be a uniquely, by the eMSP, generated ID. This field is named uid instead of id to prevent confusion with: contract_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/).

visual_number
string <= 64 characters

Visual readable number/identification as printed on the Token (RFID card), might be equal to the contract_id.

issuer
required
string <= 64 characters

Issuing company, most of the times the name of the company printed on the token (RFID card), not necessarily the eMSP.

group_id
string <= 36 characters

This ID groups a couple of tokens. This can be used to make two or more tokens work as one, so that a session can be started with one token and stopped with another, handy when a card and key-fob are given to the EV-driver. Beware that OCPP 1.5/1.6 only support group_ids (it is called parentId in OCPP 1.5/1.6) with a maximum length of 20.

valid
required
boolean

Is this Token valid

whitelist
required
string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Indicates what type of white-listing is allowed.

language
string = 2 characters

Language Code ISO 639-1. This optional field indicates the Token owner's preferred interface language. If the language is not provided or not supported then the CPO is free to choose its own language.

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

The default Charging Preference. When this is provided, and a charging session is started on an Charge Point that support Preference base Smart Charging and support this ProfileType, the Charge Point can start using this ProfileType, without this having to be set via: Set Charging Preferences.

object (EnergyContract)

When the Charge Point supports using your own energy supplier/contract at a Charge Point, information about the energy supplier/contract is needed so the CPO knows which energy supplier to use. NOTE: In a lot of countries it is currently not allowed/possible to use a drivers own energy supplier/contract at a Charge Point.

last_updated
required
string <date-time>

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

{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string",
  • "visual_number": "string",
  • "issuer": "string",
  • "group_id": "string",
  • "valid": true,
  • "whitelist": "ALWAYS",
  • "language": "st",
  • "default_profile_type": "CHEAP",
  • "energy_contract": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

ReserveNow

response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between ReserveNow requests.

required
object (Token)

Token object for how to reserve this Charge Point (and specific EVSE).

expiry_date
required
string <date-time>

The Date/Time when this reservation ends, in UTC.

reservation_id
required
string <= 36 characters

Reservation id, unique for this reservation. If the Receiver (typically CPO) Point already has a reservation that matches this reservationId for that Location it will replace the reservation.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) for which to reserve an EVSE.

evse_uid
string <= 36 characters

Optional EVSE.uid of the EVSE of this Location if a specific EVSE has to be reserved.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR.

{
  • "response_url": "http://example.com",
  • "token": {
    },
  • "expiry_date": "2019-08-24T14:15:22Z",
  • "reservation_id": "string",
  • "location_id": "string",
  • "evse_uid": "string",
  • "authorization_reference": "string"
}

StartSession

response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between StartSession requests.

required
object (Token)

Token object the Charge Point has to use to start a new session. The Token provided in this request is authorized by the eMSP.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) on which a session is to be started.

evse_uid
string <= 36 characters

Optional EVSE.uid of the EVSE of this Location on which a session is to be started. Required when connector_id is set.

connector_id
string <= 36 characters

Optional Connector.id of the Connector of the EVSE on which a session is to be started. This field is required when the capability START_SESSION_CONNECTOR_REQUIRED is set on the EVSE.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR.

{
  • "response_url": "http://example.com",
  • "token": {
    },
  • "location_id": "string",
  • "evse_uid": "string",
  • "connector_id": "string",
  • "authorization_reference": "string"
}

StopSession

response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between StopSession requests.

session_id
required
string <= 36 characters

Session.id of the Session that is requested to be stopped.

{}

UnlockConnector

response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between UnlockConnector requests.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) of which it is requested to unlock the connector.

evse_uid
required
string <= 36 characters

EVSE.uid of the EVSE of this Location of which it is requested to unlock the connector.

connector_id
required
string <= 36 characters

Connector.id of the Connector of this Location of which it is requested to unlock.

{
  • "response_url": "http://example.com",
  • "location_id": "string",
  • "evse_uid": "string",
  • "connector_id": "string"
}

Commands

Cancel a reservation

Request the Charge Point to cancel a specific reservation.

Authorizations:
ocpiAuthorization
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
response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between CancelReservation requests.

reservation_id
required
string <= 36 characters

Reservation id, unique for this reservation. If the Charge Point already has a reservation that matches this reservationId the Charge Point will replace the reservation.

Responses

Request samples

Content type
application/json
{}

Response samples

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

Reserve an EVSE

Request the Charge Point to reserve a (specific) EVSE for a Token.

Authorizations:
ocpiAuthorization
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
response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between ReserveNow requests.

required
object (Token)

Token object for how to reserve this Charge Point (and specific EVSE).

expiry_date
required
string <date-time>

The Date/Time when this reservation ends, in UTC.

reservation_id
required
string <= 36 characters

Reservation id, unique for this reservation. If the Receiver (typically CPO) Point already has a reservation that matches this reservationId for that Location it will replace the reservation.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) for which to reserve an EVSE.

evse_uid
string <= 36 characters

Optional EVSE.uid of the EVSE of this Location if a specific EVSE has to be reserved.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR.

Responses

Request samples

Content type
application/json
{
  • "response_url": "http://example.com",
  • "token": {
    },
  • "expiry_date": "2019-08-24T14:15:22Z",
  • "reservation_id": "string",
  • "location_id": "string",
  • "evse_uid": "string",
  • "authorization_reference": "string"
}

Response samples

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

Start a session

Request the Charge Point to start a transaction on the given EVSE/Connector.

Authorizations:
ocpiAuthorization
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
response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between StartSession requests.

required
object (Token)

Token object the Charge Point has to use to start a new session. The Token provided in this request is authorized by the eMSP.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) on which a session is to be started.

evse_uid
string <= 36 characters

Optional EVSE.uid of the EVSE of this Location on which a session is to be started. Required when connector_id is set.

connector_id
string <= 36 characters

Optional Connector.id of the Connector of the EVSE on which a session is to be started. This field is required when the capability START_SESSION_CONNECTOR_REQUIRED is set on the EVSE.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR.

Responses

Request samples

Content type
application/json
{
  • "response_url": "http://example.com",
  • "token": {
    },
  • "location_id": "string",
  • "evse_uid": "string",
  • "connector_id": "string",
  • "authorization_reference": "string"
}

Response samples

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

Stop a session

Request the Charge Point to stop an ongoing session.

Authorizations:
ocpiAuthorization
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
response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between StopSession requests.

session_id
required
string <= 36 characters

Session.id of the Session that is requested to be stopped.

Responses

Request samples

Content type
application/json
{}

Response samples

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

Unlock a connector

Request the Charge Point to unlock the connector.

Authorizations:
ocpiAuthorization
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
response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between UnlockConnector requests.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) of which it is requested to unlock the connector.

evse_uid
required
string <= 36 characters

EVSE.uid of the EVSE of this Location of which it is requested to unlock the connector.

connector_id
required
string <= 36 characters

Connector.id of the Connector of this Location of which it is requested to unlock.

Responses

Request samples

Content type
application/json
{
  • "response_url": "http://example.com",
  • "location_id": "string",
  • "evse_uid": "string",
  • "connector_id": "string"
}

Response samples

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