Comandos de dispositivos

Visão geral

Cada chamada atua sobre exatamente um dispositivo, identificado pelo respetivo assetId, que é o pathName devolvido por GET /assets. Não existe um endpoint em lote. Para enviar comandos para vários dispositivos, faça uma chamada por dispositivo dentro do limite de taxa. Os endpoints fazem o mesmo que as ferramentas de comando do MCP.

A chave necessita de DEVICES_COMMAND e DEVICES_READ. change-policy também necessita de POLICIES_READ. Os comandos destrutivos necessitam, em vez disso, 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 tem de estar inscrito (estado ACTIVE, INACTIVE ou SYNCHRONIZING). Alguns comandos funcionam apenas num tipo de dispositivo, tal como indicado em cada descrição abaixo: dispositivos Android Management (geridos pela Google) ou dispositivos geridos pelo agente Nomid (AOSP). Qualquer outro dispositivo recebe 409. Uma mensagem é uma notificação push para o agente Nomid e necessita de um token push registado.

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. Os campos desconhecidos são rejeitados e os campos de texto obrigatórios não podem estar em branco.

Comandos destrutivos

Quatro comandos apagam dados, removem ou substituem o bloqueio de ecrã ou terminam a gestão do dispositivo. Com uma chave de API, são executados assim que o pedido é aceite. Não existe qualquer etapa de aprovação no portal.

Necessitam de uma chave de API com DEVICES_COMMAND_DESTRUCTIVE e DEVICES_READ. A empresa também deve ativar os comandos destrutivos no acesso de agentes de IA no portal. Essa definição está desativada por predefinição e exige que os comandos de dispositivos também estejam ativados. Sem ela, o pedido devolve o código 403 com o código forbidden.

change-screen-lock-password recebe a nova palavra-passe em newPassword. O Nomid nunca a armazena, devolve ou regista em logs.

Corpos de pedido

Corpo do pedido de modo perdido

Corpo do pedido da mensagem

Exemplo: enviar uma mensagem

Substitua o id do ativo por um pathName de GET /assets e guarde a chave numa 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 o pedido foi concluído. Para uma mensagem, SUCCESS significa que o push foi aceite para entrega, não que o utilizador o tenha visto. 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 de perda devolvem IN_PROGRESS enquanto o dispositivo ainda não tiver confirmado o comando. O histórico de comandos mostra SUCCESS assim que o fizer. O endpoint de bloqueio não aceita corpo.

Exemplo: apagar 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"
}

A eliminação de dados de um dispositivo Android Management responde com IN_PROGRESS sem createdAt. Consulte o histórico de comandos para acompanhar a operação.

Respostas e o que fazer

As regras de repetição são importantes. Tentar novamente um comando cujo resultado é desconhecido pode fazer com que seja entregue duas vezes.

Corpos de erro

Os erros dos endpoints de comandos utilizam application/problem+json (RFC 9457). Nos endpoints lock, lost-mode, found e message, 401 e 429 devolvem 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, todos os erros exceto 401 contêm 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 incluem retryable. Uma resposta 202 não é um erro: transporta 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 pedidos

Os comandos estão limitados a 10 por minuto por chave de API, incluindo comandos destrutivos. O mesmo orçamento é partilhado com as ferramentas de comandos MCP, com alterações de políticas (cada chamada de proposta e aplicação) e com códigos QR de aprovisionamento, através de REST ou MCP. Em REST, os pedidos que ultrapassem o limite recebem HTTP 429 com um cabeçalho Retry-After.

Nos endpoints lock, lost-mode, found e message, apenas as chaves com DEVICES_COMMAND gastam este orçamento, e um pedido com um corpo inválido ou um ID de recurso desconhecido continua a contar, porque o limite é aplicado antes de o pedido ser validado. Os outros endpoints de comandos, chamadas de alteração de políticas e pedidos de códigos QR de aprovisionamento só o gastam após o pedido passar nas verificações de permissões e na validação de argumentos.

Registo de auditoria

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

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