Commands

OCPI 2.2.1

By Abhishek Uniyal · Updated

Commands in OCPI 2.2.1

The Commands module asks a CPO to perform an action, such as starting or stopping a charging session. The immediate ACCEPTED response means the CPO accepted the command request. It does not prove that charging started. The request supplies response_url, and the later POST reports the Charge Point result; this example has ACCEPTED followed by REJECTED. The immediate CommandResponse supplies timeout for this command. The callback uses CommandResult. The illustrative 30 seconds is this response value, not a universal deadline.

Sources (6)
"The Receiver (typically CPO) sends the requested command (via another protocol, for example: OCPP) to a Charge Point. The Charge Point will respond if it understands the command and will try to execute the command. This response doesn't always mean that the command was executed successfully. The Receiver (typically CPO) will forward the result in a new POST request to the Senders Commands interface."OCPI 2.2.1 specification · #mod_commands_flowresponse_url · URL · cardinality 1: URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between StartSession requests. token · Token · cardinality 1: 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 · CiString(36) · cardinality 1: Location.id of the Location (belonging to the CPO this request is sent to) on which a session is to be started. evse_uid · CiString(36) · cardinality ?: 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 · CiString(36) · cardinality ?: 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 · CiString(36) · cardinality ?: Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR.OCPI 2.2.1 specification · #mod_commands_startsession_objectresult · CommandResponseType · cardinality 1: Response from the CPO on the command request. timeout · int · cardinality 1: 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 send. message · DisplayText · cardinality *: Human-readable description of the result (if one can be provided), multiple languages can be provided.OCPI 2.2.1 specification · #mod_commands_commandresponse_objectresult · CommandResultType · cardinality 1: Result of the command request as sent by the Charge Point to the CPO. message · DisplayText · cardinality *: Human-readable description of the reason (if one can be provided), multiple languages can be provided.OCPI 2.2.1 specification · #mod_commands_commandresult_objectREJECTED: Command request rejected by the Charge Point.OCPI 2.2.1 specification · #mod_commands_commandresulttype_enumcountry_code · CiString(2) · cardinality 1: ISO-3166 alpha-2 country code of the MSP that 'owns' this Token. party_id · CiString(3) · cardinality 1: ID of the eMSP that 'owns' this Token (following the ISO-15118 standard). uid · CiString(36) · cardinality 1: 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 · TokenType · cardinality 1: Type of the token contract_id · CiString(36) · cardinality 1: Uniquely identifies the EV Driver contract token within the eMSP's platform (and suboperator platforms). Recommended to follow the specification for eMA ID from "eMI3 standard version V1.0" (http://emi3group.com/documents-links/[http://emi3group.com/documents-links/]) "Part 2: business objects." visual_number · string(64) · cardinality ?: Visual readable number/identification as printed on the Token (RFID card), might be equal to the contract_id. issuer · string(64) · cardinality 1: Issuing company, most of the times the name of the company printed on the token (RFID card), not necessarily the eMSP. group_id · CiString(36) · cardinality ?: 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 · boolean · cardinality 1: Is this Token valid whitelist · WhitelistType · cardinality 1: Indicates what type of white-listing is allowed. language · string(2) · cardinality ?: 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 · ProfileType · cardinality ?: 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. energy_contract · EnergyContract · cardinality ?: 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 · DateTime · cardinality 1: Timestamp when this Token was last updated (or created).OCPI 2.2.1 Tokens module · #mod_tokens_token_object

Example payload · start-session-request

{
  "response_url": "https://sender.example.invalid/results/example-command",
  "token": {
    "uid": "EXAMPLE-TOKEN",
    "type": "RFID",
    "issuer": "Example Provider",
    "valid": true,
    "whitelist": "NEVER",
    "last_updated": "2026-01-01T00:00:00Z",
    "country_code": "NL",
    "party_id": "EXB",
    "contract_id": "EXAMPLE-CONTRACT"
  },
  "location_id": "EXAMPLE-LOCATION"
}

Example payload · immediate-response

{
  "result": "ACCEPTED",
  "timeout": 30
}

Example payload · eventual-callback

{
  "result": "REJECTED"
}
Follow the remote StartSession command

Which endpoints does this module define?

These paths illustrate the requests. Use the URLs advertised by your partner, replace the placeholders and choose the matching interface. A listed method does not establish that this site's simulator implements it.

CPO · receiver interface

  • Send a command to the CPO, requesting the CPO to send the command to the Charge Point

    POST
    /ocpi/2.2.1/commands/START_SESSION
  • Send a command to the CPO, requesting the CPO to send the command to the Charge Point

    POST
    /ocpi/2.2.1/commands/STOP_SESSION
  • Send a command to the CPO, requesting the CPO to send the command to the Charge Point

    POST
    /ocpi/2.2.1/commands/RESERVE_NOW
Source
Method: Description GET: n/a POST: Send a command to the CPO, requesting the CPO to send the command to the Charge Point PUT: n/a PATCH: n/a DELETE: n/aOCPI 2.2.1 specification · #mod_commands_cpo_interface

eMSP · sender interface

  • Receive the asynchronous response from the Charge Point.

    POST
    {response_url}
Source
Method: Description GET: n/a POST: Receive the asynchronous response from the Charge Point. PUT: n/a PATCH: n/a DELETE: n/aOCPI 2.2.1 specification · #mod_commands_emsp_interface

Try an endpoint

Send a request to this site's OCPI endpoints and read the answer. It never reaches your own system.