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).
POST /devices/register
Sección titulada «POST /devices/register»Alta o re-registro del dispositivo. Público (el cuerpo lleva la identidad necesaria).
Request (campos principales)
Sección titulada «Request (campos principales)»| 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 |
Response
Sección titulada «Response»| 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.
POST /devices/ping
Sección titulada «POST /devices/ping»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.
Flujo launcher (fábrica)
Sección titulada «Flujo launcher (fábrica)»POST /devices/request-serial
Sección titulada «POST /devices/request-serial»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.
Relación con BLE
Sección titulada «Relación con BLE»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.