Comandos de dispositivo

Visão geral

Cada chamada atua em exatamente um dispositivo, identificado pelo seu assetId, que é o pathName retornado por GET /assets. Não há endpoint em massa. Para comandar vários dispositivos, faça uma chamada por dispositivo dentro do limite de taxa. Os endpoints fazem a mesma coisa que as ferramentas de comando MCP.

A chave precisa de DEVICES_COMMAND e DEVICES_READ. change-policy também precisa de POLICIES_READ. Em vez disso, os comandos destrutivos precisam de DEVICES_COMMAND_DESTRUCTIVE e DEVICES_READ. Envie a chave no cabeçalho X-API-Key. A API REST não aceita um cabeçalho Authorization.

O dispositivo deve estar inscrito (status ACTIVE, INACTIVE ou SYNCHRONIZING). Alguns comandos funcionam apenas em um tipo de dispositivo, conforme indicado em cada descrição abaixo: dispositivos Android Management (gerenciados pelo Google) ou dispositivos gerenciados pelo agente Nomid (AOSP). Qualquer outro dispositivo recebe 409. Uma mensagem é uma notificação push para o agente Nomid e precisa de um token push registrado.

Endpoints

Envie Content-Type: application/json com os endpoints lost-mode, message, launch-app, clear-app-data, change-policy e change-screen-lock-password. Os outros endpoints não aceitam corpo. Campos desconhecidos são rejeitados, e campos de texto obrigatórios não podem ficar em branco.

Comandos destrutivos

Quatro comandos apagam dados, removem ou substituem o bloqueio de tela ou encerram o gerenciamento do dispositivo. Com uma chave de API, eles são executados assim que a solicitação é aceita. Não há etapa de aprovação no portal.

Eles precisam de uma chave de API com DEVICES_COMMAND_DESTRUCTIVE e DEVICES_READ. A empresa também deve ativar comandos destrutivos no acesso de agente de IA no portal. Essa configuração fica desativada por padrão e exige que os comandos de dispositivo também estejam ativados. Sem isso, a solicitação retorna 403 com o código forbidden.

change-screen-lock-password recebe a nova senha em newPassword. O Nomid nunca a armazena, retorna ou registra em logs.

Corpos de requisição

Corpo da requisição de modo perdido

Corpo da requisição de mensagem

Exemplo: enviar uma mensagem

Substitua o ID do ativo por um pathName de GET /assets e mantenha a chave em uma variável de ambiente.

curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/message" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Please return this device", "body": "Bring it to the IT desk by 5 pm."}'

{
  "assetId": "k3x9m2pa",
  "type": "NOTIFICATION_MESSAGE",
  "status": "SUCCESS",
  "createdAt": "2026-10-06T14:30:00Z"
}

Uma resposta 200 significa que o comando foi criado. O campo status é o estado do comando quando a solicitação retornou. Para uma mensagem, SUCCESS significa que o push foi aceito para entrega, não que o usuário o visualizou. Acompanhe com GET /assets/ASSET_ID/commands.

Exemplo: bloquear um dispositivo

curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/lock" \
  -H "X-API-Key: $NOMID_API_KEY"

{
  "assetId": "k3x9m2pa",
  "type": "LOCK",
  "status": "IN_PROGRESS",
  "createdAt": "2026-10-06T14:30:00Z"
}

O lock e o modo perdido retornam IN_PROGRESS enquanto o dispositivo ainda não tiver confirmado o comando. O histórico de comandos exibirá SUCCESS assim que ele o fizer. O endpoint de bloqueio não aceita corpo de requisição.

Exemplo: limpar um dispositivo

curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/wipe" \
  -H "X-API-Key: $NOMID_API_KEY"

{
  "assetId": "k3x9m2pa",
  "type": "WIPE_COMPANY_DATA",
  "status": "IN_PROGRESS"
}

Uma limpeza de um dispositivo Android Management responde IN_PROGRESS sem createdAt. Verifique o histórico de comandos para acompanhá-la.

Respostas e o que fazer

As regras de repetição são importantes. Repetir um comando cujo resultado é desconhecido pode entregá-lo duas vezes.

Corpos de erro

Erros dos endpoints de comando usam application/problem+json (RFC 9457). Nos endpoints lock, lost-mode, found e message, 401 e 429 retornam um pequeno objeto JSON com error, message e status, 404 não tem corpo, e apenas 502 e 503 adicionam um membro booleano retryable. Nos outros endpoints, todo erro, exceto 401, são detalhes do problema com um membro code, como not_found, unsupported, forbidden, invalid_arguments ou rate_limited, e 429, 500, 502 e 503 também contêm retryable. Uma resposta 202 não é um erro: ela contém o objeto de resultado normal.

Exemplo de resposta 202

HTTP/1.1 202 Accepted

{
  "assetId": "k3x9m2pa",
  "type": "LOCK",
  "status": "UNCONFIRMED",
  "detail": "The command's outcome is unknown. Check the device's command history (list_device_commands or GET /api/v1/assets/{assetId}/commands) before retrying; it may only appear once the device acknowledges it."
}

Exemplo de resposta 503

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Command was not sent; it is safe to retry.",
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
  "retryable": true
}

Exemplo de resposta 404 de um endpoint diferente de lock, lost-mode, found e message

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No device found with assetId: k3x9m2pa",
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/reboot",
  "code": "not_found"
}

Limite de taxa

Os comandos são limitados a 10 por minuto por chave de API, comandos destrutivos inclusos. O mesmo orçamento é compartilhado com as ferramentas de comando MCP, com alterações de política (cada chamada propose e apply) e com códigos QR de provisionamento, via REST ou MCP. Via REST, solicitações que ultrapassam o limite recebem HTTP 429 com um cabeçalho Retry-After.

Nos endpoints lock, lost-mode, found e message, apenas chaves com DEVICES_COMMAND consomem esse orçamento, e uma solicitação com um corpo inválido ou um ID de ativo desconhecido ainda é contabilizada, pois o limite é aplicado antes da validação da solicitação. Os outros endpoints de comando, chamadas de alteração de política e solicitações de código QR de provisionamento só o consomem depois que a solicitação passa pelas verificações de permissão e validação de argumentos.

Trilha de auditoria

Cada comando é registrado no histórico de comandos do dispositivo no portal Nomid e atribuído à chave de API que o enviou, não a uma pessoa. A entrada mostra api-key, o ID da chave e o prefixo da chave. O histórico retornado por GET /assets/ASSET_ID/commands e pela ferramenta MCP list_device_commands contém apenas type, status, createdAt, feedbackAt e outcome, não quem enviou o comando.

• Referência da API Assets
• Tratamento de erros
• Guia do servidor MCP