> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobway.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# POST vehicle-command

> Sends a remote command to a vehicle connected to the company

<Info>
  This route starts the execution of a remote command for a single specific vehicle. The command is executed in the background. Use the GET `/vehicle-command/{command_id}` route to check the command status.
</Info>

<Warning>
  The ignition commands `enable_ignition` and `disable_ignition` require **two-step confirmation**. On the first call (without the `code` field), the command is **not executed**: the response returns `status: "Confirmation"` with a 6-digit `code` and a `message` to display to the user. To execute the command, resend the same request including the received `code`. All other commands are executed in a single call.
</Warning>

## Request

##### **Header**

<ParamField body="Authorization" type="string" required="true">
  The bearer token used to authenticate the company.
</ParamField>

<ParamField body="X-Signature" type="string" required="true">
  HMAC SHA256 signature of the request body, using the application's **sign-secret** as the key. The body must be serialized as JSON without extra spaces and with keys sorted alphabetically before generating the signature. See the example below:

  ```python theme={null}
  data = {"vin": vin, "command": command}
  body = json.dumps(data, separators=(",", ":"), sort_keys=True)
  signature = hmac.new("YOUR_SIGN_SECRET_PROVIDED_BY_MOBWAY", body.encode(), hashlib.sha256).hexdigest()
  ```

  The `code` field (when sent in the second step of ignition commands) is **not** part of the signature. Only `vin` and `command` are signed.
</ParamField>

##### **Body**

<ParamField body="vin" type="string" required="true">
  The Vehicle Identification Number (VIN) of the vehicle to which the command will be sent.
</ParamField>

<ParamField body="command" type="string" required="true">
  The [remote command](/en/command/general) to execute on the vehicle.
</ParamField>

<ParamField body="code" type="string">
  The 6-digit confirmation code returned in the first step of ignition commands (`enable_ignition` and `disable_ignition`). Provide it to execute the command in the second call. This does not apply to other commands.
</ParamField>

## Response

<ResponseField name="id" type="string">
  The unique identifier (UUID) of the command registered in the mobway system. Use this ID to check the command status later with GET `/vehicle-command/{command_id}`.
</ResponseField>

<ResponseField name="vin" type="string">
  The vehicle's unique identification number.
</ResponseField>

<ResponseField name="command" type="string">
  The command that was requested.
</ResponseField>

<ResponseField name="status" type="string">
  The initial status of the command. It can be "Confirmation", when an ignition command is waiting for the second confirmation step (resubmission with the `code`), "Pending", when the command has not yet been processed, or "Error", when the command was not executed successfully.
</ResponseField>

<ResponseField name="created" type="datetime">
  The date and time when the command was registered in the mobway system \[YYYY-MM-DD HH:MM:SS] (UTC-3).
</ResponseField>

<ResponseField name="code" type="string">
  The 6-digit confirmation code. It is present only in the confirmation response (`status: "Confirmation"`) for ignition commands. Resend the request with this value in the `code` field to execute the command.
</ResponseField>

<ResponseField name="message" type="string">
  The alert message, in Portuguese, to be displayed to the user before confirming the action. It is present only in the confirmation response.
</ResponseField>

<ResponseField name="detail" type="string">
  The cause of the request error. This field is only present when the request fails.

  <Warning>
    * "Invalid VIN. VIN must be a string. At least one VIN is required.": The request is malformed because the required `vin` parameter is missing.
    * "Invalid command. Command must be a string. At least one command is required.": The request is malformed because the required `command` parameter is missing.
    * "VIN not found or unauthorized access.": The requested VIN is invalid, is not associated with your company, or the vehicle ownership type does not allow this action.
    * "Command not found or unauthorized access.": The requested command is not available for this vehicle, either because of OEM restrictions or because it is not included in your package plan.
    * "Sign-secret not found.": The HMAC signature provided in the X-Signature header does not match any application associated with the company.
    * "X-Signature invalid.": The HMAC signature provided in the `X-Signature` header does not match the signature calculated from the request body.
    * "Failed to send command to the OEM.": An error occurred while attempting to send the command to the OEM system.
    * "Failed to initiate command with the OEM or retrieve status URL.": An error occurred while initiating the command with the OEM or obtaining the URL required to check the status later.
    * "Confirmation invalid": The provided confirmation code is invalid. Restart the flow by sending the request without the `code` field to obtain a new code.
    * "Confirmation already used": The confirmation code has already been used. Each code can be used only once. Restart the flow by sending the request without the `code` field to obtain a new one.
  </Warning>
</ResponseField>

<RequestExample>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.mobway.cloud/vehicle-command \
    --header 'Authorization: Bearer <token>' \
    --header 'X-Signature: <signature>' \
    --header 'Content-Type: application/json' \
    --data '{
      "vin": "{vin}",
      "command": "{command}"
  }'
  ```

  ```bash Request Confirmation (2nd stage of ignition commands) theme={null}
  curl --request POST \
    --url https://api.mobway.cloud/vehicle-command \
    --header 'Authorization: Bearer <token>' \
    --header 'X-Signature: <signature>' \
    --header 'Content-Type: application/json' \
    --data '{
      "vin": "{vin}",
      "command": "{command}",
      "code": "{code}"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response Pending theme={null}
  {
    "id": "8619b2df-1d68-40e1-8760-cf36f06d00b5",
    "vin": "6AHFT68CKAF501652",
    "command": "diagnostics",
    "status": "Pending",
    "created": "2023-02-14 09:51:48"
  }
  ```

  ```json Response Confirmation theme={null}
  {
    "id": "8619b2df-1d68-40e1-8760-cf36f06d00b5",
    "vin": "6AHFT68CKAF501652",
    "command": "disable_ignition",
    "status": "Confirmation",
    "code": "559289",
    "message": "<mensagem de alerta retornada pela API>"
  }
  ```

  ```json Response Error theme={null}
  {
    "detail": "X-Signature invalid."
  }
  ```
</ResponseExample>