Skip to navigation
eMSPCommands

Send a command

Starts, stops, unlocks or reserves. response is the immediate answer; the final result arrives on X-Command-Callback-Url and on GET /emsp/commands/{tracking_id}. X-Tracking-Id (or Idempotency-Key) makes the call safe to retry: the same id returns the first outcome without sending again.

emsp-gateway decides whether the charger is yours (sent over OCPP) or a roaming CPO’s (sent over OCPI in the partner’s version); route says which. Session and CDR updates for this authorization go to the session and CDR callback URLs.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

authorization_referencestringRequiredformat: "^[\x20-\x2e\x30-\x7e]{1,36}$"1-36 characters

Your id for this authorization (OCPI CiString(36), no ’/’). Sessions and CDRs carry it.

commandenumRequired
The OCPI command.
Allowed values:

Headers

X-Tracking-Idstring or nullOptionalformat: "^[\x21-\x7e]+$"1-36 characters

Idempotency key and command id (≤36 printable ASCII). Generated when absent.

Idempotency-Keystring or nullOptionalformat: "^[\x21-\x7e]+$"1-36 characters

Same as X-Tracking-Id; send one of the two.

X-Ocpi-Country-Codestring or nullOptionalformat: "^[A-Za-z]{2}$"

CPO country code, when location_id alone is ambiguous.

X-Ocpi-Party-Idstring or nullOptionalformat: "^[A-Za-z0-9]{3}$"

CPO party id, when location_id alone is ambiguous.

X-Request-Idstring or nullOptionalformat: "^[\x21-\x7e]+$"1-64 characters

Your request id; echoed on every callback.

X-Correlation-Idstring or nullOptionalformat: "^[\x21-\x7e]+$"1-128 characters

Your correlation id; echoed on every callback.

X-Command-Callback-Urlstring or nullOptional1-255 characters
HTTPS URL that gets a POST with the final command result.
X-Session-Callback-Urlstring or nullOptional1-255 characters
HTTPS URL that gets a PUT with every session update.
X-Cdr-Callback-Urlstring or nullOptional1-255 characters
HTTPS URL that gets a POST per CDR.

Request

This endpoint expects an object.
tokenobject or nullOptional

START_SESSION and RESERVE_NOW: the driver’s token.

location_idstring or nullOptional1-39 characters
OCPI location id of the charger.
evse_uidstring or nullOptional1-39 characters
OCPI EVSE uid.
connector_idstring or nullOptional1-36 characters
OCPI connector id.
session_idstring or nullOptional1-36 characters

STOP_SESSION: the OCPI session id to stop.

reservation_idstring or nullOptional1-36 characters

RESERVE_NOW and CANCEL_RESERVATION: your reservation id.

expiry_datedatetime or nullOptional

RESERVE_NOW: when the reservation ends.

Response

The route and the immediate answer; status is PENDING until the final result.

tracking_idstring
routeobject
statusenum or any
responseobject or nullOptional

The CPO’s / charger’s immediate OCPI CommandResponse.

ocpi_bodymap from strings to any or nullOptional

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
502
Bad Gateway Error
504
Gateway Timeout Error