Endpoints verificados

Todos los endpoints de la API probados de extremo a extremo con tres identidades: administrador (Bearer), usuario normal (Bearer) y clave de API (esquema Token). Cada fila indica el metodo, la ruta, la autorizacion que exige y el resultado observado.

Autenticacion

Control de acceso

Tabla de endpoints

Metodo Ruta Autorizacion Notas
POST/auth/magic-linkpublicoPide un enlace de acceso por correo. Responde igual exista o no el email (y si el usuario apago el enlace, no lo envia). 5 intentos cada 15 min.
GET/auth/magic?token={t}publicoValida el enlace y muestra una confirmacion sin consumirlo; los escaneres de correo pueden visitar esta ruta automaticamente.
POST/auth/magic/consumepublicoConsume el enlace despues de confirmar el acceso y redirige al frontend con un codigo de un solo uso (1 min).
POST/auth/handoffpublicoCanjea ese codigo por la sesion: datos del usuario + tokenIdentificador (15 min) + cookie de refresh.
POST/auth/passwordpublicoEntra con email y contraseña, si el usuario lo activo en Ajustes. Misma respuesta que /auth/handoff. Cualquier fallo: el mismo 401.
POST/auth/refreshcookieRenueva el acceso con la cookie y la rota. 409 si otra pestaña acaba de renovar (reintentar); 401 si la sesion no vale.
POST/auth/logoutcookieCierra la sesion de la cookie (revoca sus tokens) y borra la cookie.
POST/loginusuario+apikeyLogin antiguo: valida email y contraseña y envia un codigo por email.
POST/tokenusuario+apikeyValida el codigo y devuelve una sesion renovable (igual que /auth/handoff).
GET/usuario/metodos-accesoBearerFormas de entrar del usuario: {"enlace": true, "password": false}.
PUT/usuario/metodos-accesoBearer*{metodo, activo, password?, passwordActual?}. Activar la contraseña exige elegir una (min. 10). Nunca deja la cuenta sin forma de entrar (400). Sin login reciente: 428.
GET/usuarioBearer/TokenDatos del usuario autenticado.
GET/usuario/bearerTokenBearerCrea/devuelve la clave de API del usuario.
GET/usuariosadminLista paginada. Usuario normal: 403.
POST/usuariosadminAlta atomica con Zoho: si Zoho no acepta, no se crea. Con ZOHO_DESACTIVADO (local y pruebas) se crea solo en local y lo dice.
PUT/usuarios/{id}adminActualiza en local y sincroniza con Zoho; si Zoho falla, se guarda igual y la respuesta lo avisa.
DELETE/usuarios/{id}adminBaja logica (eliminado=1). En Zoho marca Usuario_en_la_app = Inactivo; si Zoho falla, la baja se hace igual y la respuesta lo avisa.
POST/usuarios/relacionaradminAsocia una planta a un usuario.
DELETE/usuarios/relacionaradminQuita la asociacion.
GET/proveedoresBearer/TokenLista de proveedores disponibles.
GET/clasesBearer/TokenClases de usuario.
GET/logsadminRegistro de la aplicacion.
POST/climaBearer/TokenCuerpo JSON: {name} o {lat,long}.
GET/plantsBearer/TokenAgregado (admin) o solo las suyas (usuario).
GET/plants?proveedor={p}adminPlantas de un proveedor.
GET/plants/details/{id}propietarioDetalle. Planta ajena: 403.
GET/plant/power/realtime/{id}propietarioTiempo real. Planta ajena: 403.
GET/plant/inventario/{id}propietarioEquipos de la planta.
GET/plant/overview/{id}propietarioSolo SolarEdge; el resto 404.
GET/plant/benefits/{id}propietarioSolarEdge y Sungrow; el resto 404.
GET/plant/alert?proveedor={p}propietario*GoodWe va por todo el parque: el admin lo ve entero y un usuario solo las de sus plantas. 503 si GoodWe no responde (no "sin alarmas").
POST/plants/graficas?proveedor={p}propietarioHistoricos por planta; la planta va en el cuerpo JSON (id, o siteId en SolarEdge). GoodWe sale de SEMS+ con el formato de siempre.
GET/plants/energy/{ids}propietarioSolarEdge: varias plantas.
GET/plant/grafica/bateria/{id}propietarioSolarEdge.
GET/plant/grafica/comparacion/{id}propietarioSolarEdge.
POST/totalrealprice?plantId={id}&proveedor={p}propietarioIngresos reales con la tarifa del cliente (GoodWe, SolarEdge, Victron). Desde el 21/10/2026 comprueba que la planta sea del usuario.

* propietario = admin, o usuario con esa planta asociada. En /plant/alert, un usuario ve solo las alarmas de sus plantas. En PUT /usuario/metodos-acceso, Bearer* = login de menos de 10 minutos o passwordActual.

Que ofrece cada proveedor

No todos los proveedores exponen todos los datos. Lo que un proveedor no ofrece responde 404 (no es un fallo, lo declara su adaptador).

Proveedor plantsdetailsrealtimegraficasinventarioalertasbenefitsoverview
GoodWe✓✓✓✓✓———
SolarEdge✓✓✓✓✓—✓✓
VictronEnergy✓✓✓✓✓✓——
Sungrow✓✓✓✓✓✓✓—
Sigenergy✓✓✓✓✓✓——

Actualizado el 21/10/2026: 219 pruebas unitarias (PHPUnit) y PHPStan pasan. El flujo de acceso por correo se comprobó en Docker local con Mailpit. Ver testing/ y documentacion/.