Zo krijgt u via de API toegang tot de gegevens van uw Heiwit-omvormer (Data Act)

Zo krijgt u via de API toegang tot de gegevens van uw Heiwit-omvormer

U kunt de gegevens van uw Heiwit-installatie ook vanuit een extern programma uitlezen, via de API. U logt in op AI-Care, opent Report › Scarica i dati del tuo impianto › Accesso via API en maakt een token aan: dat is de sleutel die het programma gebruikt om de gegevens op te vragen. De toegang is gratis en alleen-lezen, en elk token geldt voor één installatie. Dit is de procedure die Heiwit beschikbaar stelt om de toegang tot gegevens uit te oefenen die de Europese Data Act (Verordening (EU) 2023/2854) voorschrijft.

Ziet u de video niet? Bekijk hem op YouTube.

In de video ziet u de volledige procedure: toegang inschakelen, authenticatie met het token en het eerste verzoek. Hieronder vindt u alles stap voor stap uitgelegd, met de lijst van beschikbare gegevens, de limieten en enkele voorbeelden om direct te kopiëren.

Allereerst: hebt u de API echt nodig?

Als u alleen de cijfers in een Excel-bestand wilt: nee. Op de pagina Report van AI-Care staat het vak Scarica i dati del tuo impianto: kies de periode en de detaillering (per uur, per dag of per maand) en download een Excel- of CSV-bestand. U hoeft niets te configureren.

De API is handig als u wilt dat de gegevens automatisch in een ander programma binnenkomen, zonder handmatig bestanden te downloaden. Bijvoorbeeld:

• een domoticasysteem zoals Home Assistant;
• een Excel-bestand dat met één klik wordt bijgewerkt;
• het bedrijfssysteem van een onderneming, de software van een energieadviseur of een energiecoöperatie;
• een script dat u of uw technicus zelf schrijft.

Wat is een API, in eenvoudige woorden

Een API is een webadres dat bedoeld is voor programma's in plaats van voor mensen. U opent een pagina en leest die; een programma 'roept' het adres aan en ontvangt de gegevens in een geordend, direct bruikbaar formaat: JSON of CSV.

Elke aanroep bevat een token, een lange geheime sleutel. Die werkt als een wachtwoord, met twee verschillen: hij dient alleen om gegevens te lezen en geeft toegang tot slechts één installatie.

Het recht op uw gegevens: de Data Act

De Data Act is de Europese dataverordening (Verordening (EU) 2023/2854) en is van toepassing vanaf 12 september 2025. Hij geldt ook voor verbonden producten, zoals de omvormer met zijn monitoringdienst, en geeft de gebruiker twee rechten:

• toegang te krijgen tot de gegevens die door het gebruik van het product worden gegenereerd, en deze te gebruiken (artikel 4);
• ze beschikbaar te laten stellen aan een derde die hij daartoe aanwijst, bijvoorbeeld de installateur of een adviseur (artikel 5).

Daarom is de toegang tot de gegevens waar u recht op hebt gratis. Eerst controleert Heiwit of u daar recht op hebt: daarom kan het token pas worden aangemaakt nadat u bent ingelogd op AI-Care met het account waaraan de installatie is gekoppeld.

Wat u nodig hebt

• Het account van het Heiwit-portaal. AI-Care gebruikt dezelfde inloggegevens als het portaal: e-mailadres of gebruikersnaam en wachtwoord. Weet u uw wachtwoord niet meer, gebruik dan Wachtwoord herstellen op de inlogpagina.
• De installatie gekoppeld aan uw account. Als u inlogt en uw installatie niet ziet, vraag dan de klantenservice om toegang.
• Een programma dat webverzoeken kan doen: Home Assistant, Excel, Python, het commando curl of de software van uw leverancier.

Stap 1: maak het token aan

1. Ga naar ai-care.heiwit.com en log in.
2. Hebt u meerdere installaties, kies dan de installatie die u wilt.
3. Open Report in het menu.
4. Open onderaan de pagina het vak Scarica i dati del tuo impianto en vervolgens de sectie Accesso via API.
5. Voer een naam in die u eraan herinnert waarvoor het token dient, bijvoorbeeld 'Home Assistant', en klik op Crea token.
6. Kopieer het token meteen en bewaar het op een veilige plek: het wordt maar één keer getoond. U herkent het doordat het begint met aic_.

In dezelfde sectie vindt u de lijst met actieve tokens voor de installatie, met het laatste gebruik, het aantal aanroepen en de datum waarop ze worden gedeactiveerd. Met Revoca schakelt u er direct een uit.

Stap 2: doe het eerste verzoek

Alle verzoeken beginnen met dit adres:

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

Het token wordt verzonden in een header van het verzoek met de naam Authorization, voorafgegaan door het woord Bearer en een spatie:

Authorization: Bearer aic_IL_TUO_TOKEN

Voor een snelle test volstaat de terminal met het commando curl, dat al aanwezig is op Windows 10 en 11, macOS en Linux. Vervang aic_IL_TUO_TOKEN door uw token:

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

Typ op Windows in PowerShell curl.exe in plaats van curl.

U hoeft niet aan te geven welke installatie moet worden uitgelezen: dat bepaalt het token. Het antwoord ziet er ongeveer zo uit:

{
  "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
  }
}

In dit voorbeeld produceren de panelen 3.120 W: 1.670 W gaat naar het huis en 1.450 W laadt de batterij op, die op 64% staat. Met het net wordt niets uitgewisseld.

Wat u kunt uitlezen

De API heeft drie adressen, allemaal alleen-lezen (GET-verzoeken):

/status: de installatie nu

/energy: de historie

Voorbeeld: de gegevens per dag van september 2026, alleen energie en eigen verbruik.

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"

De parameters voegt u na het vraagteken aan het adres toe, gescheiden door &:

Met granularity=hour bestrijkt één verzoek maximaal 400 dagen: voor langere perioden doet u meerdere verzoeken. Met day en month kunt u de volledige historie in één keer opvragen.

De CSV gebruikt de komma als scheidingsteken en de punt voor decimalen, het meest gangbare formaat voor software. Om het bestand te openen in een Excel met Italiaanse (of Nederlandse) instellingen voegt u toe: &delimiter=semicolon&decimal=comma.

De gegevensgroepen die u kunt opvragen met fields:

Elke regel begint met de datum (date), waaraan bij de uurweergave het uur (hour) wordt toegevoegd; bij de maandweergave staat er de maand (month). Het JSON-antwoord uit het voorbeeld ziet er zo uit:

{
  "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
    }
  ]
}

Hier worden alleen de eerste regels getoond: in data staan alle 30 dagen (count).

/token: de status van het token

Geeft de naam van het token, de installatie, de aanmaakdatum, het laatste gebruik, de datum waarop het token wordt gedeactiveerd als u het niet gebruikt (expires_at), het aantal aanroepen van vandaag en de limieten. Handig om te controleren of alles werkt. Ook deze aanroep telt mee voor de daglimiet.

Hoe actueel de gegevens zijn

• Huidige status (/status): de omvormer verstuurt ongeveer elke 5 minuten een meting en de API geeft de laatst ontvangen meting terug. De API bevraagt de omvormer niet live, maar leest de gegevens die de monitoring al heeft verzameld; uw aanroepen belasten de installatie dus niet.
• Historie (/energy): het lopende uur en de lopende dag zijn onvolledig en groeien gaandeweg aan. Datums en tijden zijn in Italiaanse tijd.
• Als de omvormer de internetverbinding verliest, antwoordt de API toch met de laatst ontvangen meting: kijk naar updated_at om te zien hoe recent die is.
• De bedragen in euro zijn schattingen, berekend met de groothandelsprijs van energie (PUN) van de periode en met dezelfde formule als de tegels in AI-Care. Het is niet uw energierekening.

Regels en limieten van het token

• Eén token, één installatie. Hebt u meerdere installaties, dan maakt u voor elke installatie een token aan.
• Alleen lezen. Met het token kan niets worden gewijzigd.
• Maximaal 5 actieve tokens per installatie. Het is handig om er één per programma te gebruiken: als u er één moet uitschakelen, blijven de andere werken.
• 10 aanroepen per minuut en 300 per dag per token. De dagteller wordt om middernacht Italiaanse tijd gereset. Elk antwoord vermeldt de daglimiet in de header X-Quota-Limit en het aantal resterende aanroepen van vandaag in X-Quota-Remaining.
• Geen vaste vervaldatum. Het token wordt automatisch gedeactiveerd als het 60 dagen niet wordt gebruikt; elke aanroep schuift de vervaldatum naar later op.
• Direct intrekken met Revoca (Intrekken). Met Revoca, op de pagina Report, werkt het token meteen niet meer.

Hoe vaak de gegevens opvragen? De status verandert ongeveer elke 5 minuten, dus vaker aanroepen levert geen nieuwe gegevens op. Eén aanroep per 5 minuten is 288 aanroepen per dag: dat valt binnen de limiet, maar laat er maar 12 over. Als u hetzelfde token ook voor iets anders nodig hebt, kies dan één aanroep per 10 minuten. Voor historische gegevens volstaat één aanroep per dag.

Als er iets misgaat

Als een verzoek mislukt, antwoordt de API met een code, een afkorting (error) en een bericht in het Italiaans dat uitlegt wat u moet corrigeren. Bijvoorbeeld:

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

Kant-en-klare voorbeelden

Home Assistant

Met de RESTful-integratie van Home Assistant kunt u sensoren aanmaken die het volgende uitlezen: /status. Sla in het bestand secrets.yaml het token op, met het woord Bearer ervoor:

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Voeg vervolgens toe aan 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

Met scan_interval: 600 Home Assistant roept de API elke 10 minuten aan: 144 aanroepen per dag. De andere totalen van lifetime_kwh (teruglevering, afname, batterij) voegt u op dezelfde manier toe als de sensor ‘opgewekte energie’ en kunt u gebruiken in het Energie-dashboard.

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. Open in Excel Gegevens › Van web en kies Geavanceerd.
2. Plak als adres:
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. Vul bij de HTTP-aanvraagheaders Authorization in en daarnaast Bearer aic_IL_TUO_TOKEN.
4. Als Excel vraagt hoe u toegang wilt krijgen, kies dan Anoniem: de autorisatie staat al in de header.
5. Laad de tabel. Vanaf dat moment laadt Alles vernieuwen deze opnieuw met de nieuwe gegevens.

Zonder from en to ontvangt u altijd de laatste 30 dagen. Let op: het token blijft in het bestand opgeslagen, en wie het bestand ontvangt, kan de gegevens van de installatie lezen.

Voor installateurs en bedrijven

• Eén token per installatie. Met het hoofdaccount van de installateur ziet u in AI-Care de installaties die u beheert, en voor elke installatie kunt u een token aanmaken via de pagina Report. Limieten en vervaldatum gelden per token: met 40 installaties hebt u 40 tokens, elk met eigen 300 aanroepen per dag.
• Agentaccounts zien de sectie Accesso via API niet: daarvoor is het hoofdaccount van de installateur nodig.
• De gegevens zijn van de klant. Gebruik ze voor de diensten die u met de klant hebt afgesproken. De klant ziet op zijn pagina Report alle actieve tokens op zijn installatie, ook die door u zijn aangemaakt, met naam en laatste gebruik, en kan ze intrekken. Geef tokens duidelijke namen, bijvoorbeeld ‘Onderhoud Rossi Impianti’.
• Als een klant u zijn gegevens wil toevertrouwen (artikel 5 van de Data Act), is de eenvoudigste weg dat hij zelf een speciaal token aanmaakt en aan u overhandigt. Hij kan het intrekken wanneer de samenwerking eindigt.

Hetzelfde geldt voor softwarebedrijven, energieadviseurs en energiegemeenschappen: zij koppelen met één token per installatie, dat de eigenaar aanmaakt en aan hen overhandigt.

Beveiliging: wat deze API niet doet

• Hij verstrekt geen beheerdersgegevens van de omvormer.
• Hij wijzigt geen firmware, elektrische parameters of beveiligingsinstellingen: hij leest alleen.
• Het token geeft geen toegang tot uw AI-Care-account en ook niet tot andere installaties.

Behandel het token toch als een wachtwoord: publiceer het niet online, laat het niet in gedeelde bestanden staan en stuur het niet via chat. Vreest u dat iemand het heeft gezien, trek het dan in en maak een nieuw aan. Heiwit bewaart alleen een vingerafdruk (hash) van het token, niet het token zelf: daarom kan niemand, ook de klantenservice niet, het u opnieuw toesturen. De communicatie met de API is versleuteld (HTTPS).

Veelgestelde vragen

Wat kost het?

Niets. Toegang tot de gegevens waarop u recht hebt, is gratis.

Kan ik met de API de instellingen van de omvormer wijzigen?

Nee. De API is alleen-lezen: firmware, elektrische parameters en beveiligingen blijven onaangeroerd.

Kan ik mijn gegevens aan de installateur of een ander bedrijf geven?

Ja. Met de Data Act kunt u ze beschikbaar laten stellen aan een derde partij die u daartoe aanwijst. In de praktijk maakt u een token met een herkenbare naam aan en geeft u het aan de partij van uw keuze; u kunt het op elk moment intrekken. Voor andere verzoeken kunt u contact opnemen met de klantenservice.

Ik ben het token kwijt. Kunt u het opnieuw sturen?

Nee, want Heiwit bewaart het niet. Maak een nieuw aan en trek het oude in.

Verloopt het token?

Alleen als u het niet gebruikt: na 60 dagen zonder aanroepen wordt het automatisch gedeactiveerd. Zolang u het gebruikt, blijft het actief.

Kan ik met één token meerdere installaties uitlezen?

Nee, elk token geldt voor één installatie. Voor meerdere installaties zijn meerdere tokens nodig.

Zijn de bedragen in euro dezelfde als op de energierekening?

Nee. Het zijn schattingen, berekend met de groothandelsprijs van energie (PUN) in de betreffende periode.

Hoe ver kan ik terug in de tijd gaan?

Tot het begin van de gegevens die door de monitoring zijn vastgelegd. Met uurdetail beslaat elke aanvraag maximaal 400 dagen.

Werkt het met Home Assistant?

Ja, met de RESTful-integratie: de configuratie vindt u in de voorbeelden hierboven.

Nuttige links

• API-documentatie en overzicht van de toegankelijke gegevens: ai-care.heiwit.com/report (na het inloggen, kader Scarica i dati del tuo impianto › Accesso via API).
• Activering van de toegang en ondersteuning: ai-care.heiwit.com/login.
• Videohandleiding: Heiwit-omvormer: zo krijgt u via de API toegang tot uw gegevens.

Wettelijke referenties: Verordening (EU) 2023/2854 van het Europees Parlement en de Raad van 13 december 2023 (Data Act), in het bijzonder artikel 4, over de toegang van de gebruiker tot de gegevens, en artikel 5, over het delen ervan met derden. De toegang tot de gegevens waarop de gebruiker recht heeft is gratis, na verificatie van de bevoegdheid van de aanvrager; het beschikbaar stellen van de gegevens aan een door de gebruiker aangewezen derde gebeurt onder de voorwaarden van de verordening. De technische informatie heeft betrekking op versie 1 van de API (/api/v1) per 5 oktober 2026.

De API leest de gegevens uit die worden verzameld door AI-Care, het Heiwit-platform voor monitoring van installaties. Het hart van de installatie is deVirgo hybride omvormer, gecombineerd met de Heiwit natrium-ionbatterij van 10 kWh.