API HTTP del dispositivo

Usa HTTPS cuando un dispositivo no pueda mantener una conexión MQTT: dispositivos con batería que se despiertan, envían y vuelven a dormir, o redes que bloquean MQTT. Los mensajes HTTP se gestionan exactamente igual que los mensajes MQTT: las mismas formas de payload, las mismas reglas de claves, los mismos límites de tasa y el mismo recuento mensual de mensajes. Esta página enumera todos los endpoints a los que puede llamar un dispositivo.

Conceptos básicos

El token nunca va en la URL, salvo en los perfiles que activan Token en la URL (ver más abajo). Los certificados de cliente no se usan en la API HTTP: los dispositivos que inician sesión con X.509 usan MQTT. Cualquier ruta que no aparezca aquí responde 404.

Endpoints

No disponible por HTTP: leer atributos (GET /api/v1/attributes), esperar cambios de atributos compartidos, abrir la ventana de reclamación y pedir firmware. Estas rutas responden 404. Los dispositivos que las necesiten usan MQTT.

La telemetría usa las mismas formas de payload que MQTT. Consulta Referencia de temas y payloads MQTT. Un cuerpo en POST /api/v1/telemetry que no sea JSON se guarda como una única clave raw (hasta el tamaño raw del perfil, 4 KB por defecto).

Detalles del endpoint

{
    "ts": 1759572000000,
    "values": {
        "temperature": 21.5,
        "humidity": 40
    }
}

curl -X POST 'https://<your-host>/api/v1/telemetry' \
  -H 'Content-Type: application/json' \
  -d '{"ts":1759572000000,"values":{"temperature":21.5,"humidity":40}}'

{
    "error": "invalid_payload"
}

{
    "error": "payload_too_large"
}

{
    "error": "rate_limited"
}

{
    "current_fw_title": "boiler-fw",
    "current_fw_version": "26.10.2",
    "lan.ip": "192.168.1.1"
}

curl -X POST 'https://<your-host>/api/v1/attributes' \
  -H 'Content-Type: application/json' \
  -d '{"current_fw_title":"boiler-fw","current_fw_version":"26.10.2","lan.ip":"192.168.1.1"}'

{
    "error": "invalid_payload"
}

{
    "error": "rate_limited"
}

curl -X GET 'https://<your-host>/api/v1/rpc?timeout=20000'

{
    "id": 42,
    "method": "sys.ping",
    "params": {
        "host": "8.8.8.8",
        "count": 3
    }
}

{
    "error": "tls_required"
}

{
    "error": "timeout"
}

{
    "error": "poll_in_progress"
}

{
    "ok": true,
    "result": {
        "sent": 3,
        "received": 3,
        "avg_ms": 18.2
    }
}

curl -X POST 'https://<your-host>/api/v1/rpc/{id}' \
  -H 'Content-Type: application/json' \
  -d '{"ok":true,"result":{"sent":3,"received":3,"avg_ms":18.2}}'

{
    "error": "payload_too_large"
}

{
    "method": "app.request",
    "params": {}
}

curl -X POST 'https://<your-host>/api/v1/rpc' \
  -H 'Content-Type: application/json' \
  -d '{"method":"app.request","params":{}}'

{
    "error": "timeout"
}

{
    "deviceName": "boiler-07",
    "provisionDeviceKey": "pk_8f3b2c1e9d4a7b60",
    "provisionDeviceSecret": "ps_1c9e7f2a4b6d8e03"
}

curl -X POST 'https://<your-host>/api/v1/provision' \
  -H 'Content-Type: application/json' \
  -d '{"deviceName":"boiler-07","provisionDeviceKey":"pk_8f3b2c1e9d4a7b60","provisionDeviceSecret":"ps_1c9e7f2a4b6d8e03"}'

{
    "status": "SUCCESS",
    "credentialsType": "ACCESS_TOKEN",
    "credentialsValue": "aZ3…"
}

{
    "error": "payload_too_large"
}

Ejemplos

Envía una lectura, sellada por el servidor:

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 21.5, "humidity": 40}'

Envía lecturas almacenadas en búfer con sus propios tiempos (milisegundos desde 1970, UTC):

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[{"ts":1759572000000,"values":{"temperature":21.5}},{"ts":1759572060000,"values":{"temperature":21.7}}]'

Espera un comando y respóndelo:

curl -s "https://<device host>/api/v1/rpc?timeout=30000" -H "Authorization: Bearer <ACCESS_TOKEN>"
# → {"id": 42, "method": "sys.ping", "params": {...}}
curl -X POST "https://<device host>/api/v1/rpc/42" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json" \
  -d '{"ok": true, "result": {"sent": 3, "received": 3}}'

Códigos de estado

Estado de conexión para dispositivos HTTP

Los dispositivos HTTP no mantienen una conexión, así que un perfil con Conexión en vivo nunca los muestra en línea. Asigna a los dispositivos HTTP un perfil con Mensaje reciente (en línea mientras el último mensaje sea más reciente que el intervalo esperado multiplicado por el factor) o Solo última conexión. Consulta Estado de conexión y actividad.

Dispositivos que no pueden enviar cabeceras

Algunos dispositivos no pueden definir una cabecera Authorization. Para ellos, active Token in the URL en la pestaña Transport & auth del perfil. Entonces los dispositivos podrán usar:

POST /api/v1/{token}/telemetry
POST /api/v1/{token}/attributes

Comandos sobre HTTP sin cifrar

Una consulta larga (long poll) que no llega a Hermetry por TLS recibe solo los comandos que el perfil enumera en Commands allowed without TLS. Cualquier otro comando espera a una conexión TLS o a que expire. Si la lista está vacía, una consulta sin cifrar responde 403 tls_required.

Relacionado

• Envío de comandos a dispositivos
• Credenciales del dispositivo
• Los datos no llegan