Ir al contenido

REST del dispositivo

Estos endpoints son los que usa el dispositivo (o el launcher) contra la Core API. No son la API OAuth de consumo de datos del cliente (API pública).

Base URL: la que configure el entorno (backend.baseUrl en provisión BLE, o la URL de fábrica).

Alta o re-registro del dispositivo. Público (el cuerpo lleva la identidad necesaria).

Campo Tipo Obligatorio Notas
commercialName string sí Nombre comercial
presetId UUID sí Deriva el modelo; no enviar modelID
manufacturerId UUID/string sí Fabricante
hw_uid string sí ID de hardware único
customerId UUID sí Cliente/organización
params array sí { name, slug, min, max, unit }
specialNotifications array no { slug, name, description? }
triggers array no Definiciones de actuadores
lat, lon string no Ubicación
groupId UUID no Grupo destino
serialNumber string no Flujo launcher: completa ASSIGNED → REGISTERED
Campo Descripción
deviceId DID (UUID)
deviceSecret Secreto HTTPS del dispositivo
mqtt_uri p. ej. mqtt://host:port
mqtt_user Normalmente igual al DID
mqtt_pass Password MQTT
mqtt_telemetry_topic Topic de telemetría del entorno
mqtt_trigger_topic Topic de ACK de triggers

Errores frecuentes: 404 (manufacturer/preset), 409 (hw_uid duplicado).

Persistí deviceId, deviceSecret y credenciales MQTT en almacenamiento seguro del equipo.

Heartbeat HTTPS. Público.

Request: { "did": "<deviceId>", "rssi": <n>, "uptime": <n> }

Response: { "founded": true|false, "mqtt_telemetry_topic"?: "…", "mqtt_trigger_topic"?: "…" }

Si el DID existe, la API puede devolver topics actualizados: útil tras cambios de entorno.

Estos endpoints públicos tienen un límite por minuto. Si se supera, la respuesta es 429 con Retry-After. Los valores se editan en Configuración global y arrancan holgados para no cortar equipos reales:

Qué Cupo Default
POST /devices/ping por DID 1200/min
GET .../assignment, .../firmware, .../launcher por número de serie, y un techo aparte por IP 1200/min por serial, 20000/min por IP
POST /devices/register y POST /devices/request-serial por fabricante, y el mismo techo por IP 600/min por fabricante, 20000/min por IP

El ping no comparte el techo por IP: varios equipos en la misma red pueden hacer health check a la vez. La telemetría MQTT no pasa por este límite.

Request: { "manufacturerId": "<uuid>" }
Response: { "serialNumber": "<hex 8 chars>" } — crea dispositivo en estado ORPHAN.

GET /devices/by-serial/:serialNumber/assignment

Sección titulada «GET /devices/by-serial/:serialNumber/assignment»

Polling del launcher. Si assigned: false, aún no hay preset. Si assigned: true, incluye presetId, commercialName, datos de firmware publicado, etc. El launcher no inicia OTA de producto sin presetId.

PATCH /devices/by-serial/:serialNumber/assignment

Sección titulada «PATCH /devices/by-serial/:serialNumber/assignment»

Asignación desde panel fabricante (requiere JWT de fabricante): { "presetId", "commercialName" }.

Hay endpoints adicionales de descarga de .bin (firmware producto / launcher) fuera del alcance de esta página de contrato mínimo.

Tras la provisión BLE, el firmware arma el body de register con preset/params propios + customerId / ubicación recibidos, llama a este endpoint y solo entonces queda operativo en MQTT. Ver Provisión BLE.