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
- Bearer (JWT): cabecera Authorization: Bearer <jwt>. Es el acceso de una sesion: dura 15 minutos y se renueva solo con POST /auth/refresh. Se obtiene entrando por enlace al correo (/auth/magic-link → /auth/handoff), con email y contraseña (/auth/password) o con el login antiguo (/login + /token). Desde el 21/10/2026 ya no valen JWT sin sesion (los antiguos de 30 y 180 dias): hay que volver a entrar.
- Sesion renovable: el refresh viaja solo en una cookie HttpOnly (SameSite=Strict, __Host-esc_refresh en HTTPS), rota en cada uso y caduca a los 90 dias sin uso o a los 180 desde el login. Salir, cambiar la contraseña o el email, o desactivar la cuenta la invalida al momento. /auth/refresh y /auth/logout exigen JSON y origen permitido.
- Formas de entrar por usuario: enlace (activo por defecto) y contraseña (inactiva por defecto), en /usuario/metodos-acceso. Cambiarlas exige un login de menos de 10 minutos o la contraseña actual (si no, 428) y avisa al usuario por correo.
- Clave de API: cabecera Authorization: Token <uuid>. La crea el propio usuario con su Bearer en /usuario/bearerToken. No caduca y no depende de las sesiones: sigue igual.
- La cabecera Authorization se lee sin distinguir mayusculas (RFC 7230), asi que funciona por HTTP/1.1 y HTTP/2.
Control de acceso
- Admin (clase 1): ve y opera sobre todas las plantas y usuarios.
- Usuario (clase 2): solo sus plantas asociadas. Pedir una planta ajena devuelve 403, exista o no (no se confirma su existencia).
- El mismo control aplica tanto por Bearer como por clave de API.
Tabla de endpoints
| Metodo | Ruta | Autorizacion | Notas |
|---|---|---|---|
| POST | /auth/magic-link | publico | Pide 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} | publico | Valida el enlace y muestra una confirmacion sin consumirlo; los escaneres de correo pueden visitar esta ruta automaticamente. |
| POST | /auth/magic/consume | publico | Consume el enlace despues de confirmar el acceso y redirige al frontend con un codigo de un solo uso (1 min). |
| POST | /auth/handoff | publico | Canjea ese codigo por la sesion: datos del usuario + tokenIdentificador (15 min) + cookie de refresh. |
| POST | /auth/password | publico | Entra con email y contraseña, si el usuario lo activo en Ajustes. Misma respuesta que /auth/handoff. Cualquier fallo: el mismo 401. |
| POST | /auth/refresh | cookie | Renueva 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/logout | cookie | Cierra la sesion de la cookie (revoca sus tokens) y borra la cookie. |
| POST | /login | usuario+apikey | Login antiguo: valida email y contraseña y envia un codigo por email. |
| POST | /token | usuario+apikey | Valida el codigo y devuelve una sesion renovable (igual que /auth/handoff). |
| GET | /usuario/metodos-acceso | Bearer | Formas de entrar del usuario: {"enlace": true, "password": false}. |
| PUT | /usuario/metodos-acceso | Bearer* | {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 | /usuario | Bearer/Token | Datos del usuario autenticado. |
| GET | /usuario/bearerToken | Bearer | Crea/devuelve la clave de API del usuario. |
| GET | /usuarios | admin | Lista paginada. Usuario normal: 403. |
| POST | /usuarios | admin | Alta 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} | admin | Actualiza en local y sincroniza con Zoho; si Zoho falla, se guarda igual y la respuesta lo avisa. |
| DELETE | /usuarios/{id} | admin | Baja 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/relacionar | admin | Asocia una planta a un usuario. |
| DELETE | /usuarios/relacionar | admin | Quita la asociacion. |
| GET | /proveedores | Bearer/Token | Lista de proveedores disponibles. |
| GET | /clases | Bearer/Token | Clases de usuario. |
| GET | /logs | admin | Registro de la aplicacion. |
| POST | /clima | Bearer/Token | Cuerpo JSON: {name} o {lat,long}. |
| GET | /plants | Bearer/Token | Agregado (admin) o solo las suyas (usuario). |
| GET | /plants?proveedor={p} | admin | Plantas de un proveedor. |
| GET | /plants/details/{id} | propietario | Detalle. Planta ajena: 403. |
| GET | /plant/power/realtime/{id} | propietario | Tiempo real. Planta ajena: 403. |
| GET | /plant/inventario/{id} | propietario | Equipos de la planta. |
| GET | /plant/overview/{id} | propietario | Solo SolarEdge; el resto 404. |
| GET | /plant/benefits/{id} | propietario | SolarEdge 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} | propietario | Historicos 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} | propietario | SolarEdge: varias plantas. |
| GET | /plant/grafica/bateria/{id} | propietario | SolarEdge. |
| GET | /plant/grafica/comparacion/{id} | propietario | SolarEdge. |
| POST | /totalrealprice?plantId={id}&proveedor={p} | propietario | Ingresos 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 | plants | details | realtime | graficas | inventario | alertas | benefits | overview |
|---|---|---|---|---|---|---|---|---|
| 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/.