Cómo acceder a los datos de tu inversor Heiwit mediante API (Data Act)

Cómo acceder a los datos de tu inversor Heiwit mediante API

También puedes leer los datos de tu instalación Heiwit desde un programa externo, mediante API. Entras en AI-Care, abres Report › Scarica i dati del tuo impianto (Descarga los datos de tu instalación) › Accesso via API (Acceso vía API) y creas un token: es la clave que el programa utiliza para solicitar los datos. El acceso es gratuito, de solo lectura y cada token sirve para una sola instalación. Es el procedimiento que Heiwit pone a disposición para ejercer el acceso a los datos previsto por el Data Act europeo (Reglamento UE 2023/2854).

¿No se ve el vídeo? Míralo en YouTube.

En el vídeo ves el procedimiento completo: habilitación del acceso, autenticación con el token y primera solicitud. A continuación lo encontrarás explicado paso a paso, con la lista de datos disponibles, los límites y algunos ejemplos listos para copiar.

Antes de nada: ¿de verdad necesitas la API?

Si solo quieres los números en una hoja de Excel, no. En la página Report de AI-Care está el recuadro Scarica i dati del tuo impianto: eliges el periodo y el nivel de detalle (hora a hora, día a día o mes a mes) y descargas un archivo Excel o CSV. No hace falta configurar nada.

La API sirve cuando quieres que los datos lleguen solos a otro programa, sin descargar archivos a mano. Por ejemplo:

• un sistema de domótica como Home Assistant;
• una hoja de Excel que se actualiza con un clic;
• el software de gestión de una empresa, el software de un consultor energético o de una comunidad energética;
• un script escrito por ti o por tu técnico.

Qué es una API, en pocas palabras

Una API es una dirección web pensada para programas en lugar de para personas. Tú abres una página y la lees; un programa «llama» a la dirección y recibe los datos en un formato ordenado, listo para usar: JSON o CSV.

Cada llamada lleva consigo un token, una larga clave secreta. Funciona como una contraseña, con dos diferencias: solo sirve para leer los datos y abre una sola instalación.

El derecho a tus datos: el Data Act

El Data Act es el reglamento europeo de datos (Reglamento UE 2023/2854) y se aplica desde el 12 de septiembre de 2025. Afecta también a los productos conectados, como el inversor con su servicio de monitorización, y otorga a quienes los usan dos derechos:

• acceder a los datos generados por el uso del producto y utilizarlos (artículo 4);
• que se pongan a disposición de un tercero designado por el usuario, por ejemplo el instalador o un consultor (artículo 5).

Por eso el acceso a los datos que te corresponden es gratuito. Antes, Heiwit verifica que tengas derecho a ello: por eso el token solo se crea después de haber entrado en AI-Care con la cuenta a la que está asociada la instalación.

Qué necesitas

• La cuenta del portal Heiwit. AI-Care utiliza las mismas credenciales que el portal: correo electrónico o nombre de usuario y contraseña. Si no recuerdas la contraseña, usa Recuperar la contraseña en la página de acceso.
• La instalación asociada a tu cuenta. Si entras y no ves tu instalación, solicita la habilitación al servicio de asistencia.
• Un programa capaz de hacer solicitudes web: Home Assistant, Excel, Python, el comando curl o el software de tu proveedor.

Paso 1: crea el token

1. Ve a ai-care.heiwit.com e inicia sesión.
2. Si tienes varias instalaciones, elige la que te interese.
3. Abre Report desde el menú.
4. Al final de la página abre el recuadro Scarica i dati del tuo impianto y después la sección Accesso via API.
5. Escribe un nombre que te recuerde para qué sirve el token, por ejemplo «Home Assistant», y pulsa Crea token.
6. Copia el token inmediatamente y guárdalo en un lugar seguro: se muestra una sola vez. Lo reconoces porque empieza por aic_.

En la misma sección encontrarás la lista de tokens activos en la instalación, con el último uso, el número de llamadas y la fecha en que se desactivarán. Con Revoca desactivas uno al instante.

Paso 2: haz la primera solicitud

Todas las solicitudes parten de esta dirección:

https://ai-care.heiwit.com/api/v1

El token se envía en una cabecera (header) de la solicitud llamada Authorization, precedido de la palabra Bearer y de un espacio:

Authorization: Bearer aic_IL_TUO_TOKEN

Para una prueba rápida basta con el terminal y el comando curl, ya presente en Windows 10 y 11, macOS y Linux. Sustituye aic_IL_TUO_TOKEN por tu token:

curl -H "Authorization: Bearer aic_IL_TUO_TOKEN" "https://ai-care.heiwit.com/api/v1/status"

En Windows, en PowerShell, escribe curl.exe en lugar de curl.

No tienes que indicar qué instalación leer: lo determina el token. La respuesta es similar a esta:

{
  "plant": {
    "sn": "90xxxxxxxxxxxxxxxx",
    "name": "Casa",
    "model": "Virgo6K-S-HW",
    "installed_power_kwp": 6,
    "battery_capacity_kwh": 10
  },
  "updated_at": "2026-10-05 07:10:12",
  "now": {
    "pv_w": 3120,
    "battery_w": -1450,
    "grid_w": 0,
    "load_w": 1670,
    "battery_soc": 64,
    "battery_soh": 100,
    "work_mode": 1,
    "work_mode_label": "Self-use (autoconsumo)"
  },
  "lifetime_kwh": {
    "pv": 8421.5,
    "export": 2310.2,
    "import": 1187.4,
    "bat_charge": 2950.8,
    "bat_discharge": 2702.3
  }
}

En este ejemplo los paneles producen 3120 W: 1670 W van a la casa y 1450 W cargan la batería, que está al 64 %. Con la red no se intercambia nada.

Qué puedes leer

La API tiene tres direcciones, todas de solo lectura (solicitudes GET):

/status: la instalación ahora

/energy: el histórico

Ejemplo: los datos día a día de septiembre de 2026, solo energía y autoconsumo.

curl -H "Authorization: Bearer aic_IL_TUO_TOKEN" "https://ai-care.heiwit.com/api/v1/energy?granularity=day&from=2026-09-01&to=2026-09-30&fields=energy,derived"

Los parámetros se añaden a la dirección después del signo de interrogación, separados por &:

Con granularity=hour una solicitud abarca como máximo 400 días: para periodos más largos, haz varias solicitudes. Con day y month puedes solicitar todo el histórico de una sola vez.

El CSV usa la coma como separador y el punto para los decimales, el formato más habitual para los programas. Para abrirlo con Excel en español, añade &delimiter=semicolon&decimal=comma.

Los grupos de datos que puedes solicitar con fields:

Cada fila empieza con la fecha (date), a la que se añade la hora (hour) en el detalle horario; en el detalle mensual figura el mes (month). La respuesta JSON del ejemplo tiene este aspecto:

{
  "plant": { "sn": "90xxxxxxxxxxxxxxxx" },
  "granularity": "day",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "fields": ["energy", "derived"],
  "count": 30,
  "truncated": false,
  "generated_at": "2026-10-05T09:30:00+02:00",
  "data": [
    {
      "date": "2026-09-01",
      "pv_kwh": 31.4,
      "export_kwh": 9.8,
      "import_kwh": 1.2,
      "bat_charge_kwh": 8.7,
      "bat_discharge_kwh": 7.9,
      "self_consumption_kwh": 20.8,
      "home_load_kwh": 22.0,
      "autonomy_pct": 94.5,
      "pv_self_used_pct": 68.8
    }
  ]
}

Aquí solo se muestran las primeras filas: en data están los 30 días (count).

/token: el estado del token

Devuelve el nombre del token, la instalación, la fecha de creación, el último uso, la fecha en que se desactivará si no lo usas (expires_at), las llamadas realizadas hoy y los límites. Resulta útil para comprobar que todo funciona. Esta llamada también cuenta para el límite diario.

Grado de actualización de los datos

• Estado actual (/status): el inversor envía una lectura aproximadamente cada 5 minutos y la API devuelve la última recibida. No consulta el inversor en directo: lee los datos ya recopilados por la monitorización, por lo que tus llamadas no suponen carga para la instalación.
• Histórico (/energy): la hora y el día en curso son parciales y van aumentando. Las fechas y horas son las de Italia.
• Si el inversor pierde la conexión a internet, la API responde igualmente con la última lectura recibida: consulta updated_at para saber lo reciente que es.
• Los valores en euros son estimaciones, calculadas con el precio de la energía en el mercado mayorista (PUN) del periodo y con la misma fórmula que los paneles de AI-Care. No son tu factura.

Reglas y límites del token

• Un token, una instalación. Si tienes varias instalaciones, crea un token para cada una.
• Solo lectura. Con el token no se puede modificar nada.
• Hasta 5 tokens activos por instalación. Conviene usar uno para cada programa: si tienes que desactivar uno, los demás siguen funcionando.
• 10 llamadas por minuto y 300 al día por cada token. El recuento diario se reinicia a medianoche, hora italiana. Cada respuesta indica el límite diario en la cabecera X-Quota-Limit y las llamadas que quedan hoy en X-Quota-Remaining.
• Sin caducidad fija. El token se desactiva automáticamente si permanece sin usarse durante 60 días; cada llamada aplaza la caducidad.
• Revocación inmediata. Con Revoca, en la página Report, el token deja de funcionar de inmediato.

¿Con qué frecuencia solicitar los datos? El estado cambia aproximadamente cada 5 minutos, por lo que llamar con más frecuencia no aporta datos nuevos. Una llamada cada 5 minutos supone 288 llamadas al día: entra dentro del límite, pero solo deja libres 12. Si también necesitas el mismo token para otra cosa, elige una llamada cada 10 minutos. Para el histórico basta con una llamada al día.

Si algo no funciona

Cuando una solicitud no se completa correctamente, la API responde con un código, una sigla (error) y un mensaje en italiano que explica qué corregir. Por ejemplo:

{ "error": "invalid_token", "message": "Token non valido o revocato." }

Ejemplos listos para usar

Home Assistant

Con la integración RESTful de Home Assistant puedes crear sensores que lean /status. En el archivo secrets.yaml guarda el token, con la palabra Bearer delante:

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Después añade en configuration.yaml:

rest:
  - resource: https://ai-care.heiwit.com/api/v1/status
    scan_interval: 600
    headers:
      Authorization: !secret heiwit_aicare
    sensor:
      - name: "Heiwit produzione FV"
        value_template: "{{ value_json.now.pv_w }}"
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
      - name: "Heiwit batteria"
        value_template: "{{ value_json.now.battery_soc }}"
        unit_of_measurement: "%"
        device_class: battery
      - name: "Heiwit scambio con la rete"
        value_template: "{{ value_json.now.grid_w }}"
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
      - name: "Heiwit energia prodotta"
        value_template: "{{ value_json.lifetime_kwh.pv }}"
        unit_of_measurement: "kWh"
        device_class: energy
        state_class: total_increasing

Con scan_interval: 600 Home Assistant llama a la API cada 10 minutos: 144 llamadas al día. Los demás totales de lifetime_kwh (vertido, consumo de red, batería) se añaden igual que el sensor «energía producida» y pueden usarse en el panel Energía.

Python

import requests

TOKEN = "aic_IL_TUO_TOKEN"

risposta = requests.get(
    "https://ai-care.heiwit.com/api/v1/energy",
    headers={"Authorization": f"Bearer {TOKEN}"},
    params={"granularity": "day", "from": "2026-09-01", "to": "2026-09-30"},
    timeout=30,
)
risposta.raise_for_status()

for giorno in risposta.json()["data"]:
    print(giorno["date"], giorno["pv_kwh"], "kWh prodotti")

Excel

1. En Excel abre Datos › De la web y elige Avanzado.
2. Como dirección, pega:
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. En los encabezados de la solicitud HTTP escribe Authorization y, al lado, Bearer aic_IL_TUO_TOKEN.
4. Si Excel pregunta cómo acceder, elige Anónimo: la autorización ya está en la cabecera.
5. Carga la tabla. A partir de ese momento Actualizar todo la vuelve a descargar con los datos nuevos.

Sin from y to recibes siempre los últimos 30 días. Atención: el token queda guardado en el archivo, y quien reciba el archivo puede leer los datos de la instalación.

Para instaladores y empresas

• Un token por instalación. Con la cuenta principal del instalador ves en AI-Care las instalaciones que gestionas, y para cada una puedes crear un token desde la página Report. Los límites y la caducidad se aplican token por token: con 40 instalaciones tienes 40 tokens, cada uno con sus 300 llamadas al día.
• Las cuentas de agente no ven la sección Accesso via API (Acceso vía API): se necesita la cuenta principal del instalador.
• Los datos son del cliente. Utilízalos para los servicios acordados con él. El cliente ve en su página Report todos los tokens activos en su instalación, incluidos los creados por ti, con nombre y último uso, y puede revocarlos. Asigna a los tokens nombres claros, por ejemplo «Mantenimiento Rossi Impianti».
• Si un cliente quiere confiarte sus datos (artículo 5 del Data Act), lo más sencillo es que él cree un token específico y te lo entregue. Podrá revocarlo cuando termine la relación.

Lo mismo vale para empresas de software, consultores energéticos y comunidades energéticas: se conectan con un token por instalación, que el titular crea y les entrega.

Seguridad: lo que esta API no hace

• No proporciona credenciales de administración del inversor.
• No modifica el firmware, los parámetros eléctricos ni los ajustes de protección: solo lee.
• El token no abre tu cuenta AI-Care ni da acceso a otras instalaciones.

Aun así, trata el token como una contraseña: no lo publiques en internet, no lo dejes en archivos compartidos, no lo envíes por chat. Si temes que alguien lo haya visto, revócalo y crea uno nuevo. Heiwit conserva solo una huella (hash) del token, no el token en sí: por eso nadie, ni siquiera el servicio de asistencia, puede volver a enviártelo. Las comunicaciones con la API están cifradas (HTTPS).

Preguntas más frecuentes

¿Cuánto cuesta?

Nada. El acceso a los datos que te corresponden es gratuito.

¿Con la API puedo cambiar los ajustes del inversor?

No. La API es de solo lectura: no toca el firmware, los parámetros eléctricos ni las protecciones.

¿Puedo dar mis datos al instalador o a otra empresa?

Sí. El Data Act te permite ponerlos a disposición de un tercero designado por ti. En la práctica, creas un token con un nombre reconocible y se lo entregas a quien hayas elegido; puedes revocarlo cuando quieras. Para otras solicitudes, escribe al servicio de asistencia.

He perdido el token. ¿Me lo pueden volver a enviar?

No, porque Heiwit no lo conserva. Crea uno nuevo y revoca el antiguo.

¿Caduca el token?

Solo si no lo utilizas: tras 60 días sin llamadas se desactiva automáticamente. Mientras lo utilices, permanece activo.

¿Puedo consultar varias instalaciones con un solo token?

No, cada token es válido para una instalación. Para varias instalaciones se necesitan varios tokens.

¿Los valores en euros son los de la factura?

No. Son estimaciones calculadas con el precio de la energía en el mercado mayorista (PUN) del periodo.

¿Hasta qué fecha anterior puedo consultar?

Hasta el inicio de los datos registrados por la monitorización. Con el detalle horario, cada solicitud abarca como máximo 400 días.

¿Funciona con Home Assistant?

Sí, con la integración RESTful: encontrarás la configuración en los ejemplos anteriores.

Enlaces útiles

• Documentación de la API y lista de los datos accesibles: ai-care.heiwit.com/report (tras iniciar sesión, recuadro Scarica i dati del tuo impianto (Descarga los datos de tu instalación) › Accesso via API (Acceso vía API)).
• Habilitación del acceso y asistencia: ai-care.heiwit.com/login.
• Vídeo guía: Inversor Heiwit: cómo acceder a tus datos mediante API.

Referencias normativas: Reglamento (UE) 2023/2854 del Parlamento Europeo y del Consejo, de 13 de diciembre de 2023 (Data Act), en particular el artículo 4, sobre el acceso del usuario a los datos, y el artículo 5, sobre su puesta a disposición de terceros. El acceso a los datos que corresponden al usuario es gratuito, previa verificación de la legitimación del solicitante; la puesta a disposición de los datos a un tercero designado por el usuario se realiza en las condiciones previstas por el reglamento. Las indicaciones técnicas se refieren a la versión 1 de la API (/api/v1) a 5 de octubre de 2026.

La API lee los datos recopilados por AI-Care, la plataforma Heiwit de monitorización de instalaciones. El corazón de la instalación es elinversor híbrido Virgo, combinado con la batería Heiwit de iones de sodio de 10 kWh.