> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ocpplab.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ocpplab.io/_mcp/server. # Send a command POST https://api.ocpplab.io/emsp/commands/{authorization_reference}/{command} Content-Type: application/json 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. Reference: https://docs.ocpplab.io/api-reference/emsp/commands/send ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `authorization_reference` (string, required) — Your id for this authorization (OCPI CiString(36), no '/'). Sessions and CDRs carry it. - `command` (enum, required) — The OCPI command. - Allowed values: `START_SESSION`, `STOP_SESSION`, `UNLOCK_CONNECTOR`, `RESERVE_NOW`, `CANCEL_RESERVATION` ### Headers - `X-Tracking-Id` (string, optional, nullable) — Idempotency key and command id (≤36 printable ASCII). Generated when absent. - `Idempotency-Key` (string, optional, nullable) — Same as X-Tracking-Id; send one of the two. - `X-Ocpi-Country-Code` (string, optional, nullable) — CPO country code, when location_id alone is ambiguous. - `X-Ocpi-Party-Id` (string, optional, nullable) — CPO party id, when location_id alone is ambiguous. - `X-Request-Id` (string, optional, nullable) — Your request id; echoed on every callback. - `X-Correlation-Id` (string, optional, nullable) — Your correlation id; echoed on every callback. - `X-Command-Callback-Url` (string, optional, nullable) — HTTPS URL that gets a POST with the final command result. - `X-Session-Callback-Url` (string, optional, nullable) — HTTPS URL that gets a PUT with every session update. - `X-Cdr-Callback-Url` (string, optional, nullable) — HTTPS URL that gets a POST per CDR. ### Body (application/json) This endpoint expects an EmspCommandBody. - `token` (CommandToken, optional, nullable) — START_SESSION and RESERVE_NOW: the driver's token. - `location_id` (string, optional, nullable) — OCPI location id of the charger. - `evse_uid` (string, optional, nullable) — OCPI EVSE uid. - `connector_id` (string, optional, nullable) — OCPI connector id. - `session_id` (string, optional, nullable) — STOP_SESSION: the OCPI session id to stop. - `reservation_id` (string, optional, nullable) — RESERVE_NOW and CANCEL_RESERVATION: your reservation id. - `expiry_date` (datetime, optional, nullable) — RESERVE_NOW: when the reservation ends. ## Response ### 200 The route and the immediate answer; ``status`` is ``PENDING`` until the final result. - `tracking_id` (string, required) - `route` (CommandAcceptedRoute, required) - `status` (CommandAcceptedStatus, required) - `response` (CommandResponseOut, optional, nullable) — The CPO's / charger's immediate OCPI CommandResponse. - `ocpi_body` (map from string to any, optional, nullable) ## Errors ### 400 Bad Request Error The body's authorization_reference differs from the path - `detail` (string, required) — Human-readable error message returned by the API. ### 401 Unauthorized Error Missing or invalid Bearer token - `detail` (string, required) — Human-readable error message returned by the API. ### 404 Not Found Error Location not found for your organization - `detail` (string, required) — Human-readable error message returned by the API. ### 409 Conflict Error Not remote-startable, or X-Tracking-Id reused for another command - `detail` (string, required) — Human-readable error message returned by the API. ### 422 Unprocessable Entity Error The request does not match the schema - `detail` (list of ValidationError, optional) — One entry per invalid field. ### 429 Too Many Requests Error Gateway rate limit reached; retry after the given seconds - `detail` (string, required) — Human-readable error message returned by the API. ### 502 Bad Gateway Error Gateway unreachable, failing, or misconfigured - `detail` (string, required) — Human-readable error message returned by the API. ### 504 Gateway Timeout Error Gateway timed out - `detail` (string, required) — Human-readable error message returned by the API. ## Types ### CommandToken The driver's token as you issued it; emsp-gateway fills the rest from its copy. - `uid` (string, required) — OCPI token uid. - `type` (string, required) — OCPI token type, e.g. ``APP_USER``. - `contract_id` (string, optional, nullable) — eMA id of the contract. ### CommandAcceptedRoute ### CommandAcceptedStatus ### CommandResponseOut The CPO's / charger's immediate OCPI CommandResponse. - `result` (CommandResponseOutResult, optional, nullable) - `timeout` (integer, optional, nullable) ### ValidationError Why one field is invalid. - `loc` (list of ValidationErrorLocItems, required) — Where the field is: ``body`` / ``query`` / ``path`` / ``header``, then its name. - `msg` (string, required) — What is wrong, in English. - `type` (string, required) — Machine-readable error code, e.g. ``missing``. - `input` (any, optional) — The value that was sent. - `ctx` (ValidationErrorCtx, optional) — Details of the rule that failed, e.g. `{"le": 200}`. ### CommandAcceptedRoute_Own - `location` (EmspGatewaySchemaCommandsLocationKey, required) - `kind` ("own", optional, default: own) - `evse_uid` (string, optional, nullable) - `connector_id` (string, optional, nullable) - `ocpi_version` (CommandAcceptedRouteOwnOcpiVersion, optional, nullable) ### CommandAcceptedRoute_Roaming - `location` (EmspGatewaySchemaCommandsLocationKey, required) - `partner_id` (integer, required) - `ocpi_version` (CommandAcceptedRouteRoamingOcpiVersion, required) - `cpo_id` (string, required) - `kind` ("roaming", optional, default: roaming) - `evse_uid` (string, optional, nullable) - `connector_id` (string, optional, nullable) ### CommandResponseOutResult ### ValidationErrorLocItems ### ValidationErrorCtx Details of the rule that failed, e.g. `{"le": 200}`. ### EmspGatewaySchemaCommandsLocationKey - `country_code` (string, required) - `party_id` (string, required) - `location_id` (string, required) ### CommandAcceptedRouteOwnOcpiVersion ### CommandAcceptedRouteRoamingOcpiVersion ## Examples **Request** ```json { "token": { "uid": "DRIVER-1", "type": "APP_USER", "contract_id": "FR-EZP-C00000001-4" }, "location_id": "LOC-1", "evse_uid": "LOC-1-E1", "connector_id": "1" } ``` **Response** ```json { "tracking_id": "6f1c2b0e-3c4d-4e5f-8a9b-0c1d2e3f4a5b", "route": { "kind": "roaming", "location": { "country_code": "DE", "party_id": "ENA", "location_id": "LOC-1" }, "evse_uid": "LOC-1-E1", "connector_id": "1", "partner_id": 21, "ocpi_version": "2.2.1", "cpo_id": "DE*ENA" }, "status": "PENDING", "response": { "result": "ACCEPTED", "timeout": 30 }, "ocpi_body": { "token": { "uid": "DRIVER-1", "type": "APP_USER", "contract_id": "FR-EZP-C00000001-4" }, "location_id": "LOC-1", "evse_uid": "LOC-1-E1", "connector_id": "1", "authorization_reference": "EZP-AUTH-0001" } } ``` **SDK Code** ```python import requests url = "https://api.ocpplab.io/emsp/commands/EZP-AUTH-0001/START_SESSION" payload = { "token": { "uid": "DRIVER-1", "type": "APP_USER", "contract_id": "FR-EZP-C00000001-4" }, "location_id": "LOC-1", "evse_uid": "LOC-1-E1", "connector_id": "1" } headers = { "X-Tracking-Id": "6f1c2b0e-3c4d-4e5f-8a9b-0c1d2e3f4a5b", "X-Command-Callback-Url": "https://api.easyplug.example/hooks/command", "X-Session-Callback-Url": "https://api.easyplug.example/hooks/session", "X-Cdr-Callback-Url": "https://api.easyplug.example/hooks/cdr", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.ocpplab.io/emsp/commands/EZP-AUTH-0001/START_SESSION'; const options = { method: 'POST', headers: { 'X-Tracking-Id': '6f1c2b0e-3c4d-4e5f-8a9b-0c1d2e3f4a5b', 'X-Command-Callback-Url': 'https://api.easyplug.example/hooks/command', 'X-Session-Callback-Url': 'https://api.easyplug.example/hooks/session', 'X-Cdr-Callback-Url': 'https://api.easyplug.example/hooks/cdr', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"token":{"uid":"DRIVER-1","type":"APP_USER","contract_id":"FR-EZP-C00000001-4"},"location_id":"LOC-1","evse_uid":"LOC-1-E1","connector_id":"1"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ocpplab.io/emsp/commands/EZP-AUTH-0001/START_SESSION" payload := strings.NewReader("{\n \"token\": {\n \"uid\": \"DRIVER-1\",\n \"type\": \"APP_USER\",\n \"contract_id\": \"FR-EZP-C00000001-4\"\n },\n \"location_id\": \"LOC-1\",\n \"evse_uid\": \"LOC-1-E1\",\n \"connector_id\": \"1\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Tracking-Id", "6f1c2b0e-3c4d-4e5f-8a9b-0c1d2e3f4a5b") req.Header.Add("X-Command-Callback-Url", "https://api.easyplug.example/hooks/command") req.Header.Add("X-Session-Callback-Url", "https://api.easyplug.example/hooks/session") req.Header.Add("X-Cdr-Callback-Url", "https://api.easyplug.example/hooks/cdr") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ocpplab.io/emsp/commands/EZP-AUTH-0001/START_SESSION") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Tracking-Id"] = '6f1c2b0e-3c4d-4e5f-8a9b-0c1d2e3f4a5b' request["X-Command-Callback-Url"] = 'https://api.easyplug.example/hooks/command' request["X-Session-Callback-Url"] = 'https://api.easyplug.example/hooks/session' request["X-Cdr-Callback-Url"] = 'https://api.easyplug.example/hooks/cdr' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"token\": {\n \"uid\": \"DRIVER-1\",\n \"type\": \"APP_USER\",\n \"contract_id\": \"FR-EZP-C00000001-4\"\n },\n \"location_id\": \"LOC-1\",\n \"evse_uid\": \"LOC-1-E1\",\n \"connector_id\": \"1\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ocpplab.io/emsp/commands/EZP-AUTH-0001/START_SESSION") .header("X-Tracking-Id", "6f1c2b0e-3c4d-4e5f-8a9b-0c1d2e3f4a5b") .header("X-Command-Callback-Url", "https://api.easyplug.example/hooks/command") .header("X-Session-Callback-Url", "https://api.easyplug.example/hooks/session") .header("X-Cdr-Callback-Url", "https://api.easyplug.example/hooks/cdr") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"token\": {\n \"uid\": \"DRIVER-1\",\n \"type\": \"APP_USER\",\n \"contract_id\": \"FR-EZP-C00000001-4\"\n },\n \"location_id\": \"LOC-1\",\n \"evse_uid\": \"LOC-1-E1\",\n \"connector_id\": \"1\"\n}") .asString(); ``` ```php request('POST', 'https://api.ocpplab.io/emsp/commands/EZP-AUTH-0001/START_SESSION', [ 'body' => '{ "token": { "uid": "DRIVER-1", "type": "APP_USER", "contract_id": "FR-EZP-C00000001-4" }, "location_id": "LOC-1", "evse_uid": "LOC-1-E1", "connector_id": "1" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'X-Cdr-Callback-Url' => 'https://api.easyplug.example/hooks/cdr', 'X-Command-Callback-Url' => 'https://api.easyplug.example/hooks/command', 'X-Session-Callback-Url' => 'https://api.easyplug.example/hooks/session', 'X-Tracking-Id' => '6f1c2b0e-3c4d-4e5f-8a9b-0c1d2e3f4a5b', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ocpplab.io/emsp/commands/EZP-AUTH-0001/START_SESSION"); var request = new RestRequest(Method.POST); request.AddHeader("X-Tracking-Id", "6f1c2b0e-3c4d-4e5f-8a9b-0c1d2e3f4a5b"); request.AddHeader("X-Command-Callback-Url", "https://api.easyplug.example/hooks/command"); request.AddHeader("X-Session-Callback-Url", "https://api.easyplug.example/hooks/session"); request.AddHeader("X-Cdr-Callback-Url", "https://api.easyplug.example/hooks/cdr"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"token\": {\n \"uid\": \"DRIVER-1\",\n \"type\": \"APP_USER\",\n \"contract_id\": \"FR-EZP-C00000001-4\"\n },\n \"location_id\": \"LOC-1\",\n \"evse_uid\": \"LOC-1-E1\",\n \"connector_id\": \"1\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Tracking-Id": "6f1c2b0e-3c4d-4e5f-8a9b-0c1d2e3f4a5b", "X-Command-Callback-Url": "https://api.easyplug.example/hooks/command", "X-Session-Callback-Url": "https://api.easyplug.example/hooks/session", "X-Cdr-Callback-Url": "https://api.easyplug.example/hooks/cdr", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "token": [ "uid": "DRIVER-1", "type": "APP_USER", "contract_id": "FR-EZP-C00000001-4" ], "location_id": "LOC-1", "evse_uid": "LOC-1-E1", "connector_id": "1" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ocpplab.io/emsp/commands/EZP-AUTH-0001/START_SESSION")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```