Comandos de dispositivos

Descripción general

Cada llamada actúa sobre exactamente un dispositivo, identificado por su assetId, que es el pathName devuelto por GET /assets. No hay un endpoint masivo. Para enviar comandos a varios dispositivos, realice una llamada por dispositivo dentro del límite de frecuencia. Los endpoints hacen lo mismo que las herramientas de comandos de MCP.

La clave necesita DEVICES_COMMAND y DEVICES_READ. change-policy también necesita POLICIES_READ. Los comandos destructivos necesitan DEVICES_COMMAND_DESTRUCTIVE y DEVICES_READ en su lugar. Envíe la clave en el encabezado X-API-Key. La API REST no acepta un encabezado Authorization.

El dispositivo debe estar inscrito (estado ACTIVE, INACTIVE o SYNCHRONIZING). Algunos comandos solo funcionan en un tipo de dispositivo, tal como indica cada descripción a continuación: dispositivos Android Management (administrados por Google) o dispositivos administrados por el agente de Nomid (AOSP). Cualquier otro dispositivo recibe 409. Un mensaje es una notificación push para el agente de Nomid y necesita un token push registrado.

Endpoints

Envíe Content-Type: application/json con los endpoints lost-mode, message, launch-app, clear-app-data, change-policy y change-screen-lock-password. Los demás endpoints no admiten cuerpo. Los campos desconocidos se rechazan y los campos de texto obligatorios no pueden estar vacíos.

Comandos destructivos

Cuatro comandos borran datos, eliminan o reemplazan el bloqueo de pantalla, o finalizan la gestión del dispositivo. Con una clave de API, se ejecutan tan pronto como se acepta la solicitud. No hay ningún paso de aprobación en el portal.

Requieren una clave de API con DEVICES_COMMAND_DESTRUCTIVE y DEVICES_READ. La empresa también debe habilitar los comandos destructivos en el acceso de agentes de IA en el portal. Esa configuración está desactivada de forma predeterminada y requiere que los comandos de dispositivo también estén activados. Sin ella, la solicitud devuelve 403 con el código forbidden.

change-screen-lock-password recibe la nueva contraseña en newPassword. Nomid nunca la almacena, devuelve ni registra.

Cuerpos de solicitud

Cuerpo de solicitud de modo perdido

Cuerpo de solicitud de mensaje

Ejemplo: enviar un mensaje

Reemplace el id del activo con un pathName de GET /assets, y mantenga la clave en una variable de entorno.

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"
}

Una respuesta 200 significa que el comando fue creado. El campo status es el estado del comando cuando se devolvió la solicitud. Para un mensaje, SUCCESS significa que el push fue aceptado para su entrega, no que el usuario lo haya visto. Haga un seguimiento con GET /assets/ASSET_ID/commands.

Ejemplo: bloquear un 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"
}

lock y el modo perdido devuelven IN_PROGRESS mientras el dispositivo aún no haya confirmado el comando. El historial de comandos muestra SUCCESS una vez que lo hace. El endpoint lock no acepta ningún cuerpo.

Ejemplo: borrar un 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"
}

El borrado de un dispositivo de Android Management responde IN_PROGRESS sin createdAt. Consulte el historial de comandos para realizar el seguimiento.

Respuestas y qué hacer

Las reglas de reintento son importantes. Reintentar un comando cuyo resultado se desconoce puede hacer que se entregue dos veces.

Cuerpos de error

Los errores de los endpoints de comandos utilizan application/problem+json (RFC 9457). En los endpoints lock, lost-mode, found y message, 401 y 429 devuelven un objeto JSON pequeño con error, message y status, 404 no tiene cuerpo, y solo 502 y 503 agregan un miembro booleano retryable. En los demás endpoints, cada error excepto 401 corresponde a detalles del problema con un miembro code, como not_found, unsupported, forbidden, invalid_arguments o rate_limited, y 429, 500, 502 y 503 también incluyen retryable. Una respuesta 202 no es un error: incluye el objeto de resultado normal.

Ejemplo de respuesta 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."
}

Ejemplo de respuesta 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
}

Ejemplo de respuesta 404 de un endpoint distinto de lock, lost-mode, found y 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"
}

Límite de frecuencia

Los comandos están limitados a 10 por minuto por clave de API, comandos destructivos incluidos. Este mismo cupo se comparte con las herramientas de comandos de MCP, con los cambios de políticas (cada llamada propose y apply) y con los códigos QR de aprovisionamiento, ya sea mediante REST o MCP. Mediante REST, las solicitudes que superan el límite reciben HTTP 429 con un encabezado Retry-After.

En los endpoints lock, lost-mode, found y message, solo las claves con DEVICES_COMMAND consumen este cupo, y una solicitud con un cuerpo no válido o un ID de activo desconocido sigue contando, ya que el límite se aplica antes de que se valide la solicitud. Los demás endpoints de comandos, las llamadas de cambio de políticas y las solicitudes de códigos QR de aprovisionamiento solo lo consumen una vez que la solicitud ha superado las comprobaciones de permisos y la validación de argumentos.

Registro de auditoría

Cada comando se registra en el historial de comandos del dispositivo en el portal de Nomid y se atribuye a la clave de API que lo envió, no a una persona. La entrada muestra api-key, el ID de clave y el prefijo de clave. El historial devuelto por GET /assets/ASSET_ID/commands y por la herramienta MCP list_device_commands solo contiene type, status, createdAt, feedbackAt y outcome, no quién envió el comando.

• Referencia de la API de activos
• Gestión de errores
• Guía del servidor MCP