API docs by Redocly

OCPI 2.3.0 - ChargingProfiles Module - Sender Interface (2.2.1)

Download OpenAPI specification:

URL: https://evroaming.org

The Sender Interface is typically implemented by market roles like the eMSP or SCSP. It receives the asynchronous responses from the Charge Point via the CPO, and updated ActiveChargingProfiles when the CPO knows the profile has changed.

For the POST method: The URL structure is open for the Sender to define. The URL is provided to the Receiver via the response_url field. The path shown here is a typical implementation pattern.

For the PUT method: The endpoint structure is {chargingprofiles_endpoint_url}/{session_id}.

OCPI 2.3.0 Specification

Schemas

ChargingProfileResultType

string <enum> (ChargingProfileResultType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the EVSE.

REJECTED

ChargingProfile request rejected by the EVSE.

UNKNOWN

No Charging Profile(s) were found by the EVSE matching the request.

Result of a ChargingProfile request that the EVSE sends via the CPO to the eMSP.

"ACCEPTED"

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": [
    ]
}

ActiveChargingProfile

start_date_time
required
string <date-time>

Date and time at which the Charge Point has calculated this ActiveChargingProfile. All time measurements within the profile are relative to this timestamp.

required
object (ChargingProfile)

Charging profile structure defines a list of charging periods.

{
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "charging_profile": {
    }
}

ActiveChargingProfileResult

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

ChargingProfile request accepted by the EVSE.

REJECTED

ChargingProfile request rejected by the EVSE.

UNKNOWN

No Charging Profile(s) were found by the EVSE matching the request.

The EVSE will indicate if it was able to process the request for the ActiveChargingProfile

object (ActiveChargingProfile)

The requested ActiveChargingProfile, if the result field is set to: ACCEPTED

{
  • "result": "ACCEPTED",
  • "profile": {
    }
}

ChargingProfileResult

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

ChargingProfile request accepted by the EVSE.

REJECTED

ChargingProfile request rejected by the EVSE.

UNKNOWN

No Charging Profile(s) were found by the EVSE matching the request.

The EVSE will indicate if it was able to process the new/updated charging profile.

{
  • "result": "ACCEPTED"
}

ClearProfileResult

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

ChargingProfile request accepted by the EVSE.

REJECTED

ChargingProfile request rejected by the EVSE.

UNKNOWN

No Charging Profile(s) were found by the EVSE matching the request.

The EVSE will indicate if it was able to process the removal of the charging profile (ClearChargingProfile).

{
  • "result": "ACCEPTED"
}

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
}

ChargingProfiles

Receive asynchronous charging profile result

Receive the asynchronous response from the Charge Point.

As the Sender interface is called by the Receiver (typically CPO) on the URL given response_url in the Sender request to the Receiver interface. It is up to the implementation of the Sender (typically SCSP) to determine what parameters are put in the URL. The Sender sends a URL in the POST method body to the Receiver. The Receiver is required to use this URL for the asynchronous response by the Charge Point. It is advised to make this URL unique for every request to differentiate simultaneous commands, for example by adding a unique id as a URL segment.

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

Choice: one of three. ActiveChargingProfileResult: Result of the GET ActiveChargingProfile request, from the Charge Point. ChargingProfileResult: Result of the PUT ChargingProfile request, from the Charge Point. ClearProfileResult: Result of the DELETE ChargingProfile request, from the Charge Point.

One of
result
required
string <enum> (ChargingProfileResultType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the EVSE.

REJECTED

ChargingProfile request rejected by the EVSE.

UNKNOWN

No Charging Profile(s) were found by the EVSE matching the request.

The EVSE will indicate if it was able to process the request for the ActiveChargingProfile

object (ActiveChargingProfile)

The requested ActiveChargingProfile, if the result field is set to: ACCEPTED

Responses

Request samples

Content type
application/json
Example
{
  • "result": "ACCEPTED",
  • "profile": {
    }
}

Response samples

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

Receive updated ActiveChargingProfile

Updates the Sender (typically SCSP) when the Receiver (typically CPO) knows the ActiveChargingProfile has changed.

The Receiver SHALL call this interface every time it knows changes have been made that influence the ActiveChargingProfile for an ongoing session AND the Sender has at least once successfully called the charging profile Receiver PUT interface for this session (SetChargingProfile). If the Receiver doesn’t know the ActiveChargingProfile has changed (EVSE does not notify the Receiver (typically CPO) of the change) it is not required to call this interface.

The Receiver SHALL NOT call this interface for any session where the Sender has never, successfully called the charging profile Receiver PUT interface for this session (SetChargingProfile).

The Receiver SHALL send a useful relevant duration of ActiveChargingProfile to send to the Sender. As a guide: between 5 and 60 minutes. If the Sender wants a longer ActiveChargingProfile the Sender can always do a GET with a longer duration.

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

The new ActiveChargingProfile. If there is no longer any charging profile active, the ActiveChargingProfile SHALL reflect this by showing the maximum charging capacity of the EVSE.

start_date_time
required
string <date-time>

Date and time at which the Charge Point has calculated this ActiveChargingProfile. All time measurements within the profile are relative to this timestamp.

required
object (ChargingProfile)

Charging profile structure defines a list of charging periods.

Responses

Request samples

Content type
application/json
{
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "charging_profile": {
    }
}

Response samples

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