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.
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.
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.