API pública
La API pública permite que el backend de tu organización consulte datos de AlertIA y reciba avisos firmados por HTTPS, sin usar el JWT de un usuario del dashboard.
Todas las rutas viven bajo el prefijo /public/v1. La base URL es la del Core API de tu entorno (por ejemplo https://api.ejemplo.com).
Contenido
Sección titulada «Contenido»| Tema | Descripción |
|---|---|
| Autenticación OAuth | client_credentials, token Bearer, scopes y rate limits |
| Recursos | Dispositivos, carpetas y tableros NOC |
| Telemetría | Última lectura e histórico (pull, máx. 7 días) |
| Webhooks | Alertas y digest periódico de flota (HMAC) |
Flujo rápido
Sección titulada «Flujo rápido»- En el dashboard: Integraciones → crear una aplicación de integración (elegí los permisos / scopes).
- Guardá el
client_secret(se muestra una sola vez; si se pierde, rotá el secreto). - Pedí un token:
POST /public/v1/oauth/token. - Llamá a los
GETconAuthorization: Bearer <access_token>. - Opcional: configurá uno o más webhooks
httpspara alertas y, si querés, un digest de flota.
Mapa de endpoints
Sección titulada «Mapa de endpoints»| Método | Ruta | Scope |
|---|---|---|
POST |
/public/v1/oauth/token |
— (público; rate limit propio) |
GET |
/public/v1/devices |
devices.read |
GET |
/public/v1/folders |
folders.read |
GET |
/public/v1/boards |
boards.read |
GET |
/public/v1/boards/{boardId} |
boards.read |
GET |
/public/v1/devices/{deviceId}/telemetry/latest |
telemetry.read |
GET |
/public/v1/devices/{deviceId}/telemetry/history |
telemetry.read |
Los webhooks no se administran por esta API en v1: se configuran en el dashboard (Integraciones). AlertIA hace POST a tu URL.
Tenancy
Sección titulada «Tenancy»El token OAuth queda atado a una organización (la de la app de integración). Solo vas a ver datos de esa organización; no hace falta enviar un customerId en la URL de lectura.
Errores HTTP comunes
Sección titulada «Errores HTTP comunes»| Código | Significado |
|---|---|
400 |
Parámetros inválidos (p. ej. rango de fechas) |
401 |
Token ausente, expirado o no válido para esta API |
403 |
Scope insuficiente para el recurso |
404 |
Recurso inexistente o de otra organización |
429 |
Rate limit; reintentá respetando Retry-After si viene |
503 |
Emisión de tokens no disponible en el entorno |
Relación con el protocolo de dispositivo
Sección titulada «Relación con el protocolo de dispositivo»Esta API es para backends de clientes que consumen datos. El alta y telemetría que publica un dispositivo / agente está documentada en Protocolo (MQTT, REST de dispositivo, etc.).