RUUF Solar API

API HTTP con los datos de tu sistema solar RUUF cada 5 minutos: producción, consumo, red y batería, en tiempo real y como historial. Versión alpha.

Índice: Acceso · Endpoints · Ejemplos · Datos · Errores · Home Assistant

Los datos vienen de tu inversor a través de los servidores de RUUF. No es una conexión local al equipo: llegan cada 5 minutos, con unos 2 minutos de atraso.

Acceso

Necesitas un token personal (empieza con ruuf_sk_) que te entrega RUUF. Envíalo en cada consulta:

Authorization: Bearer ruuf_sk_...

No compartas tu token: da acceso a los datos de tu planta. Si crees que se filtró, pídenos uno nuevo y desactivamos el anterior.

Endpoints

Base: https://solar-api.ruuf.cl. Todo es GET. Energía en kWh, potencia en W, horas en UTC y días en hora de Chile.

Ruta	Qué entrega
`/v1/me`	Las plantas de tu token (`station` es el código de tu planta).
`/v1/now` `/v1/plants/{station}/now`	Estado actual: contadores de energía de toda la vida, energía de hoy, potencia promedio de los últimos 5 minutos y batería.
`/v1/plants/{station}/series`	Historial. Parámetros: `from` y `to` (fechas `YYYY-MM-DD`; `to` no se incluye), `step` = `5m` \| `1h` \| `1d`, `format` = `json` \| `csv`. Máximo 31 días en 5m, 93 en 1h y 1100 en 1d.

Ejemplos

curl -H "Authorization: Bearer $TOKEN" https://solar-api.ruuf.cl/v1/now

curl -H "Authorization: Bearer $TOKEN" \
  "https://solar-api.ruuf.cl/v1/plants/35035146/series?from=2026-10-01&to=2026-11-01&step=1h&format=csv" -o octubre.csv

Python:

import requests

API = "https://solar-api.ruuf.cl"
headers = {"Authorization": "Bearer ruuf_sk_..."}

now = requests.get(f"{API}/v1/now", headers=headers, timeout=30).json()
print(now["energy_kwh"]["solar_production"], "kWh generados en total")

serie = requests.get(f"{API}/v1/plants/{now['plant']}/series", headers=headers, timeout=60,
                     params={"from": "2026-10-01", "to": "2026-11-01", "step": "5m"}).json()
for fila in serie["rows"]:
    print(fila["start"], fila["solar_production"], fila["home_consumption"])

Para un historial largo en 5 minutos, consulta de a un mes (máximo 31 días por consulta).

Datos

Respuesta de `/now`

{
  "plant": "35035146",
  "collected_at": "2026-11-03T21:35:00Z",
  "stale": false,
  "energy_kwh": {
    "solar_production": 8390.79,
    "grid_export": 4994.85,
    "home_consumption": 8740.79,
    "grid_import": 5344.85,
    "battery_charge": null,
    "battery_discharge": null
  },
  "today_kwh": { "solar_production": 13.28, "grid_export": 9, "home_consumption": 6.76, "grid_import": 2.48, ... },
  "power_w": { "solar": 960, "home": 480, "grid_import": 0, "grid_export": 480, "grid": -480, "battery": null, ... },
  "battery_soc": null,
  "interval_minutes": 5
}

Campo	Significado
`energy_kwh.*`	Contadores acumulados desde el inicio de tu sistema. Nunca bajan, así que sirven directo para el panel de Energía de Home Assistant (`total_increasing`).
`solar_production`	Energía generada por los paneles.
`grid_import` / `grid_export`	Energía comprada a la red / inyectada a la red.
`home_consumption`	Consumo total de la casa.
`battery_charge` / `battery_discharge`	Energía que entró / salió de la batería (`null` si no tienes).
`power_w.grid`	Positivo cuando compras a la red, negativo cuando inyectas.
`power_w.battery`	Positivo cargando, negativo descargando.
`stale`	`true` si llevamos más de 20 minutos sin datos nuevos de tu inversor.

Notas sobre los datos

En 5m cada fila es la energía de esos 5 minutos. Si faltan filas, el inversor no reportó. A veces el inversor repite una lectura; la fila siguiente trae los dos intervalos juntos.
En 1h y 1d, la energía que el resumen diario del inversor registra pero las lecturas de 5 minutos no alcanzaron a capturar se suma en la última hora del día y la fila queda marcada con corrected. Cada fila trae también totals, los contadores acumulados al cierre de esa hora o día.
Antes de que comenzara la medición cada 5 minutos (febrero de 2026 en las primeras plantas) solo hay datos diarios.

Errores y límites

`401`	Falta el token o no es válido.
`404`	La planta no existe o no pertenece a tu token.
`429`	Más de 60 consultas por minuto. Los datos cambian cada 5 minutos, así que no hace falta consultar más seguido.
`503`	Estamos calculando el historial de tu planta por primera vez. Reintenta en un minuto (`Retry-After`).

Integraciones: Home Assistant

Si usas Home Assistant, no necesitas programar nada. Elige una de estas dos opciones.

Opción A: integración RUUF Solar (recomendada)

Crea los sensores y carga todo tu historial en el panel de Energía.

Descargar integración (v0.1.0)

Descomprime el zip y copia la carpeta custom_components/ruuf_solar dentro de /config/custom_components/. Puedes usar el add-on Samba, SSH o File editor.
Reinicia Home Assistant.
Ve a Ajustes → Dispositivos y servicios → Agregar integración → RUUF Solar y pega tu token.
En unos minutos se carga tu historial hora a hora. En Ajustes → Paneles → Energía elige las estadísticas que empiezan con «RUUF <estación>»:
- Producción solar: solar production
- Consumo de la red: grid import; devuelto a la red: grid export
- Batería, si tienes: battery charge (entra) y battery discharge (sale)

Opción B: paquete YAML (sin instalar nada)

Usa la integración REST que ya viene con Home Assistant. Solo registra desde que lo instalas, sin historial previo.

Descargar ruuf_solar.yaml

Guárdalo como /config/packages/ruuf_solar.yaml. En configuration.yaml debe estar:
```
homeassistant:
  packages: !include_dir_named packages
```
En /config/secrets.yaml agrega (con la palabra Bearer):
```
ruuf_solar_token: "Bearer ruuf_sk_..."
```
Reinicia y elige los sensores «RUUF ...» en el panel de Energía.

Contacto

Es una versión alpha y tus comentarios nos ayudan a mejorarla. Escríbenos por WhatsApp a RUUF.