> ## 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

> Envia um comando remoto para um veículo conectados à empresa

<Info>
  Esta rota inicia a execução de um comando remoto para um único veículo específico. A execução do comando ocorre em segundo plano. Use a rota GET `/vehicle-command/{command_id}` para verificar o status do comando.
</Info>

<Warning>
  Os comandos de ignição `enable_ignition` e `disable_ignition` exigem **confirmação em duas etapas**. Na primeira chamada (sem o campo `code`), o comando **não é executado**: a resposta retorna `status: "Confirmation"` com um `code` de 6 dígitos e uma `message` para exibir ao usuário. Para executar, reenvie a mesma requisição incluindo o `code` recebido. Os demais comandos executam em chamada única.
</Warning>

## Request

##### **Header**

<ParamField body="Authorization" type="string" required="true">
  É o token ao portador utilizado para autenticar a empresa.
</ParamField>

<ParamField body="X-Signature" type="string" required="true">
  Assinatura HMAC SHA256 do corpo da requisição, usando o **sign-secret** da aplicação como chave. O corpo deve ser serializado em JSON sem espaços extras e com chaves ordenadas alfabeticamente antes de gerar a assinatura. Veja o exemplo a seguir:

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

  O campo `code` (quando enviado na segunda etapa dos comandos de ignição) **não** faz parte da assinatura, apenas `vin` e `command` são assinados.
</ParamField>

##### **Body**

<ParamField body="vin" type="string" required="true">
  Indica o Vehicle Identification Number (VIN) do veículo para o qual o comando será enviado.
</ParamField>

<ParamField body="command" type="string" required="true">
  Indica o [comando remoto](https://docs.mobway.cloud/command/general) que se deseja executar no veículo.
</ParamField>

<ParamField body="code" type="string">
  Indica o código de confirmação de 6 dígitos retornado na primeira etapa dos comandos de ignição (`enable_ignition` e `disable_ignition`). Informe-o para executar o comando na segunda chamada. Não se aplica aos demais comandos.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Indica o identificador único (UUID) do comando registrado no sistema da mobway. Use este ID para verificar o status do comando posteriormente em GET `/vehicle-command/{command_id}`.
</ResponseField>

<ResponseField name="vin" type="string">
  Indica o número de identificação único do veículo.
</ResponseField>

<ResponseField name="command" type="string">
  Indica o comando que foi solicitado.
</ResponseField>

<ResponseField name="status" type="string">
  Indica o status inicial do comando. Pode ser "Confirmation", quando um comando de ignição aguarda a segunda etapa de confirmação (reenvio com o `code`), "Pending", em que o comando ainda não foi processado, ou "Error", quando o comando não foi executado corretamente.
</ResponseField>

<ResponseField name="created" type="datetime">
  Indica a data e hora em que o comando foi registrado no sistema da mobway \[YYYY-MM-DD HH:MM:SS] (UTC-3).
</ResponseField>

<ResponseField name="code" type="string">
  Indica o código de confirmação de 6 dígitos. Presente apenas na resposta de confirmação (`status: "Confirmation"`) dos comandos de ignição. Reenvie a requisição com este valor no campo `code` para executar o comando.
</ResponseField>

<ResponseField name="message" type="string">
  Indica a mensagem de alerta, em português, a ser exibida ao usuário antes de confirmar a ação. Presente apenas na resposta de confirmação.
</ResponseField>

<ResponseField name="detail" type="string">
  Indica a cause do erro na requisição. Esse campo só estará presente em caso de falha na requisição.

  <Warning>
    * "Invalid VIN. VIN must be a string. At least one VIN is required.": A requisição está mal formada pela falta do parâmetro obrigatório `vin`.
    * "Invalid command. Command must be a string. At least one command is required.": A requisição está mal formada pela falta do parâmetro obrigatório `command`.
    * "VIN not found or unauthorized access.": O VIN solicitado é inválido, não está associado à sua empresa, ou o tipo de propriedade do veículo não permite essa ação.
    * "Command not found or unauthorized access.": O comando solicitado não está disponível para este veículo, seja por restrições do OEM ou por não estar incluído no seu plano de pacotes.
    * "Sign-secret not found.": A assinatura HMAC fornecida no header X-Signature não corresponde a nenhum aplicação relacionada a empresa.
    * "X-Signature invalid.": A assinatura HMAC fornecida no header `X-Signature` não corresponde à assinatura calculada com base no corpo da requisição.
    * "Failed to send command to the OEM.": Ocorreu um erro ao tentar enviar o comando para o sistema da OEM.
    * "Failed to initiate command with the OEM or retrieve status URL.": Ocorreu um erro ao iniciar o comando com o OEM ou ao obter a URL necessária para verificar o status posteriormente.
    * "Confirmation invalid": O código de confirmação informado é inválido. Reinicie o fluxo enviando a requisição sem o campo `code` para obter um novo código.
    * "Confirmation already used": O código de confirmação já foi utilizado. Cada código é de uso único. Reinicie o fluxo enviando a requisição sem o campo `code` para obter um novo.
  </Warning>
</ResponseField>

<RequestExample>
  ```bash Requisição 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 Requisição Confirmação (2ª etapa dos comandos de ignição) 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 Resposta Pendente theme={null}
  {
    "id": "8619b2df-1d68-40e1-8760-cf36f06d00b5",
    "vin": "6AHFT68CKAF501652",
    "command": "diagnostics",
    "status": "Pending",
    "created": "2023-02-14 09:51:48"
  }
  ```

  ```json Resposta Confirmação 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 Resposta Erro theme={null}
  {
    "detail": "X-Signature invalid."
  }
  ```
</ResponseExample>