API docs by Redocly

OCPI 2.3.0 - ChargingProfiles Module - Receiver Interface (2.3.0)

Download OpenAPI specification:

URL: https://evroaming.org

The Receiver Interface is typically implemented by market roles like the CPO. It enables a Sender (typically eMSP or SCSP) to send ChargingProfiles to a Location/EVSE, request the ActiveChargingProfile, or clear an existing ChargingProfile.

The ChargingProfiles module is designed to work asynchronously. The Receiver checks if it can send the request to a Charge Point and responds with a status. The actual result from the Charge Point is sent asynchronously via POST to the Sender interface.

Endpoint structure: {chargingprofiles_endpoint_url}/{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
}

ChargingProfileResponseType

string <enum> (ChargingProfileResponseType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the CPO, request will be forwarded to the EVSE.

NOT_SUPPORTED

The ChargingProfiles not supported by this CPO, Charge Point, EVSE etc.

REJECTED

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

TOO_OFTEN

ChargingProfile request rejected by the CPO, requests are sent more often than allowed.

UNKNOWN_SESSION

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

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

"ACCEPTED"

ChargingProfileResponse

result
required
string <enum> (ChargingProfileResponseType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the CPO, request will be forwarded to the EVSE.

NOT_SUPPORTED

The ChargingProfiles not supported by this CPO, Charge Point, EVSE etc.

REJECTED

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

TOO_OFTEN

ChargingProfile request rejected by the CPO, requests are sent more often than allowed.

UNKNOWN_SESSION

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

Response from the CPO on the ChargingProfile request.

timeout
required
integer

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

{
  • "result": "ACCEPTED",
  • "timeout": 0
}

ChargingRateUnit

string <enum> (ChargingRateUnit)
Enum Description
W

Watts (power). This is the total allowed charging power. It is usually more convenient to use this for DC charging.

A

Amperes (current). The amount of Ampere per phase, not the sum of all phases. It is usually more convenient to use this for AC charging.

Unit in which a charging profile is defined.

"W"

ChargingProfilePeriod

start_period
required
integer

Start of the period, in seconds from the start of profile. The value of StartPeriod also defines the stop time of the previous period.

limit
required
number

Charging rate limit during the profile period, in the applicable chargingRateUnit, for example in Amperes (A) or Watts (W). Accepts at most one digit fraction (e.g. 8.1).

{
  • "start_period": 0,
  • "limit": 0
}

ChargingProfile

start_date_time
string <date-time>

Starting point of an absolute profile. If absent the profile will be relative to start of charging.

duration
integer

Duration of the charging profile in seconds. If the duration is left empty, the last period will continue indefinitely or until end of the transaction in case start_date_time is absent.

charging_rate_unit
required
string <enum> (ChargingRateUnit)
Enum Description
W

Watts (power). This is the total allowed charging power. It is usually more convenient to use this for DC charging.

A

Amperes (current). The amount of Ampere per phase, not the sum of all phases. It is usually more convenient to use this for AC charging.

The unit of measure.

min_charging_rate
number

Minimum charging rate supported by the EV. The unit of measure is defined by the chargingRateUnit. This parameter is intended to be used by a local smart charging algorithm to optimize the power allocation for in the case a charging process is inefficient at lower charging rates. Accepts at most one digit fraction (e.g. 8.1).

Array of objects (ChargingProfilePeriod)

List of ChargingProfilePeriod elements defining maximum power or current usage over time.

{
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "charging_rate_unit": "W",
  • "min_charging_rate": 0,
  • "charging_profile_period": [
    ]
}

SetChargingProfile

required
object (ChargingProfile)

Contains limits for the available power or current over time.

response_url
required
string <uri>

URL that the ChargingProfileResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between GET ActiveChargingProfile requests.

{
  • "charging_profile": {
    },
  • "response_url": "http://example.com"
}

ChargingProfiles

Get the ActiveChargingProfile for a session

Retrieves the ActiveChargingProfile as it is currently planned for the the given session.

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

Session.id of the Session object.

query Parameters
duration
required
integer

Length of the requested ActiveChargingProfile in seconds. Balance the duration between maximizing the information gained and the data usage and computation to execute on the request. Warning: asking for longer duration than necessary might result in additional data costs, while its added value diminishes with every change in the schedule.

response_url
required
string <uri>

URL that the ActiveChargingProfileResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between GET ActiveChargingProfile requests.

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 update a ChargingProfile for a session

Creates a new ChargingProfile on a session, or replaces an existing ChargingProfile on the EVSE.

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

SetChargingProfile object with information needed to set/update the Charging Profile for a session.

required
object (ChargingProfile)

Contains limits for the available power or current over time.

response_url
required
string <uri>

URL that the ChargingProfileResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between GET ActiveChargingProfile requests.

Responses

Request samples

Content type
application/json
{
  • "charging_profile": {
    },
  • "response_url": "http://example.com"
}

Response samples

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

Clear a ChargingProfile for a session

Clears the ChargingProfile set by the eMSP on the given session.

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

Session.id of the Session object.

query Parameters
response_url
required
string <uri>

URL that the ClearProfileResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between DELETE ChargingProfile requests.

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