API de dispositivos y perfiles

Estas rutas gestionan dispositivos y perfiles de dispositivo desde código. Las rutas cuelgan de https://<your host>/tenant/<tenantId>. Las convenciones (paginación, cuerpos estrictos, horas) están en REST API basics.

Dispositivos

Listar dispositivos

GET /api/iot/devices (las páginas empiezan en 1)

{
  "devices": [
    {
      "deviceId": "6f1c…",
      "name": "pump-station-04",
      "label": "Pump station 4",
      "type": "pump-controller",
      "serial": null,
      "deviceProfileId": "a1b2…",
      "status": "ACTIVE",
      "isGateway": false,
      "gatewayDeviceId": null,
      "model": null,
      "fwTitle": null,
      "fwVersion": null,
      "online": true,
      "active": true,
      "lastConnectAt": "2026-11-08T06:12:03.000Z",
      "lastDisconnectAt": null,
      "lastActivityAt": "2026-11-09T09:41:10.000Z",
      "lastRemoteIp": "203.0.113.20",
      "lastTransport": "mqtts",
      "additionalInfo": {},
      "createdAt": "2026-10-01T08:00:00.000Z",
      "updatedAt": "2026-11-08T06:12:03.000Z"
    }
  ],
  "total": 1
}

online es null en un perfil cuya regla de online es Last seen only. GET /api/iot/devices/{deviceId} responde { "device": {...} } con los mismos campos más profileName y profileTransport.

Crear un dispositivo

{
    "name": "pump-station-04",
    "label": "Pump station 4",
    "deviceProfileId": "a1b2…"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/devices' \
  -H 'Content-Type: application/json' \
  -d '{"name":"pump-station-04","label":"Pump station 4","deviceProfileId":"a1b2…"}'

{
    "device": {
        "deviceId": "6f1c…",
        "name": "pump-station-04",
        "status": "ACTIVE",
        "…": "…"
    },
    "credential": {
        "credential": {
            "credentialId": "…",
            "type": "ACCESS_TOKEN",
            "…": "…"
        },
        "secret": {
            "token": "Xq3…"
        }
    }
}

{
    "message": "The device limit of this account is reached.",
    "code": "FORBIDDEN",
    "details": {
        "key": "max_devices",
        "limit": 43,
        "current": 43,
        "adding": 1
    }
}

{
    "message": "A device with this name already exists.",
    "code": "CONFLICT",
    "details": {
        "reason": "name_taken"
    }
}

Cambiar un dispositivo

PATCH /api/iot/devices/{deviceId} acepta cualquiera de name, label, type, deviceProfileId, isGateway, additionalInfo, status (ACTIVE o DISABLED). Envíe solo lo que cambia. Un dispositivo en cuarentena se aprueba mediante el aprovisionamiento, no aquí: «A quarantined device is activated through provisioning, not edited here.» Un nuevo nombre, un nuevo perfil o la desactivación finalizan la sesión activa del dispositivo; se reconecta con la nueva configuración.

Eliminar un dispositivo

DELETE responde { "message": "Device deleted." }. Las lecturas del dispositivo se eliminan en segundo plano. Un dispositivo que sigue en uso se rechaza con 409, por ejemplo: «The device is still in use by 1 asset placement or relation (iot_asset).» Quítelo de su activo y elimine antes sus relaciones: véase Placing devices y Relations.

Detalles de conexión

GET /api/iot/devices/{deviceId}/connection no devuelve nada secreto:

{
  "connection": {
    "mqtt": { "host": "mqtt.example.com", "port": 8883, "tls": true },
    "httpBase": "https://acme.example.com",
    "topics": { "telemetry": "v1/telemetry", "attributes": "v1/attributes", "rpcRequest": "v1/rpc/req/+", "rpcResponse": "v1/rpc/res/{id}" },
    "telemetryKeys": [{ "key": "temperature", "type": "number" }]
  }
}

mqtt es null cuando el perfil no admite MQTT en ese listener; rpcRequest y rpcResponse son null en el esquema Legacy compatible.

Registros

• GET .../connections?page=1&pageSize=50: conexiones y desconexiones, de más reciente a más antiguo (las páginas empiezan en 1, pageSize hasta 100).
• GET .../log?page=1&pageSize=50&source=connection|audit: el registro de conexiones y las filas de auditoría del dispositivo combinados, de más reciente a más antiguo. page × pageSize puede ser como máximo 1,000.

Credenciales del dispositivo

Todas requieren iot_device.credentials.manage. Cambiar, rotar y revocar finalizan la credencial anterior de inmediato (no hay periodo de gracia) y desconectan el dispositivo.

Cuerpos de PUT:

{ "type": "ACCESS_TOKEN" }
{ "type": "MQTT_BASIC", "username": "pump04", "clientId": "pump04", "password": null }
{ "type": "X509_CERTIFICATE", "certificateId": "…" }

Para MQTT_BASIC, omita password (o use null) para obtener una generada. Una contraseña elegida necesita al menos 16 caracteres, variada, sin contener el nombre de usuario ni el client id. El nombre de usuario provision está reservado. La respuesta es { "credential": {...}, "secret": { "token": "…" } } o { ..., "secret": { "password": "…" } }, mostrada una sola vez; una credencial X.509 no tiene secreto. Una credencial X.509 se rota adjuntando un nuevo certificado: «An X.509 credential is rotated by attaching a new certificate.» Véase Device credentials.

Perfiles de dispositivo

Campos de ordenación: name, transport, online, updated. Una lista responde { "profiles": [...], "total": n }; un perfil { "profile": {...} }.

Crear un perfil

Un perfil nuevo necesita un name (hasta 128 caracteres) y un onlineRule: LIVE_SOCKET (Live connection), UPLINK_WINDOW (Recent message, también necesita expectedIntervalS, de 60 a 604,800) o LAST_SEEN_ONLY (Last seen only). Cada otro campo toma su valor por defecto.

{
  "name": "Cold room sensor",
  "onlineRule": "UPLINK_WINDOW",
  "expectedIntervalS": 300,
  "transportType": "MQTT",
  "telemetrySchema": [
    { "key": "temperature", "type": "number", "unit": "°C", "label": "Temperature", "min": -30, "max": 10, "decimals": 1 }
  ]
}

Campos seleccionados y sus rangos:

Lea primero un perfil existente para ver todos los campos con su valor actual; el editor de perfiles cubre los mismos campos con explicaciones, consulte Perfiles de dispositivo.

Rechazos

Un cuerpo que incumple una regla de campo devuelve 400 con los problemas en issues, cada uno con su path y message, por ejemplo online_rule_required (un perfil nuevo necesita una regla de conexión), expected_interval_required (Mensaje reciente necesita expectedIntervalS) o online_rule_not_allowed (la regla de conexión no encaja con el transporte).

Otros rechazos incluyen details.reason, por ejemplo: