Så får du tillgång till data från din Heiwit-växelriktare via API (Data Act)

Så får du tillgång till data från din Heiwit-växelriktare via API

Du kan även läsa data från din Heiwit-anläggning från ett externt program via API. Logga in i AI-Care, öppna Report › Scarica i dati del tuo impianto (Ladda ner data från din anläggning) › Accesso via API (Åtkomst via API) och skapa en token: det är nyckeln som programmet använder för att begära data. Åtkomsten är kostnadsfri, ger endast läsbehörighet och varje token gäller för en enda anläggning. Det är den procedur som Heiwit tillhandahåller för att utöva den rätt till tillgång till data som föreskrivs i EU:s dataförordning Data Act (förordning (EU) 2023/2854).

Syns inte videon? Titta på YouTube.

I videon ser du hela proceduren: aktivering av åtkomsten, autentisering med token och första begäran. Nedan förklaras den steg för steg, med en lista över tillgängliga data, begränsningarna och några exempel som är klara att kopiera.

Först och främst: behöver du verkligen API:t?

Om du bara vill ha siffrorna i ett Excel-ark, nej. På sidan Report i AI-Care finns rutan Scarica i dati del tuo impianto: välj period och upplösning (timme för timme, dag för dag eller månad för månad) och ladda ner en Excel- eller CSV-fil. Du behöver inte konfigurera något.

API:t behövs när du vill att data ska komma automatiskt till ett annat program, utan att ladda ner filer manuellt. Till exempel:

• ett hemautomationssystem som Home Assistant;
• ett Excel-ark som uppdateras med ett klick;
• ett företags affärssystem, programvaran hos en energirådgivare eller en energigemenskap;
• ett skript som du eller din tekniker har skrivit.

Vad är ett API, enkelt förklarat

Ett API är en webbadress avsedd för program i stället för människor. Du öppnar en sida och läser den; ett program ”anropar” adressen och får data i ett strukturerat format, klart att använda: JSON eller CSV.

Varje anrop skickar med en token, en lång hemlig nyckel. Den fungerar som ett lösenord, med två skillnader: den används bara för att läsa data och ger åtkomst till en enda anläggning.

Rätten till dina data: Data Act

Data Act är EU:s dataförordning (förordning (EU) 2023/2854) och tillämpas från den 12 september 2025. Den omfattar även uppkopplade produkter, som växelriktaren med dess övervakningstjänst, och ger användarna två rättigheter:

• få tillgång till de data som genereras genom användningen av produkten och använda dem (artikel 4);
• få dem tillgängliggjorda för en tredje part som användaren har utsett, till exempel installatören eller en rådgivare (artikel 5).

Därför är tillgången till de data du har rätt till kostnadsfri. Först kontrollerar Heiwit att du har rätt till dem: därför kan en token bara skapas efter inloggning i AI-Care med det konto som anläggningen är kopplad till.

Det här behöver du

• Kontot till Heiwit-portalen. AI-Care använder samma inloggningsuppgifter som portalen: e-post eller användarnamn och lösenord. Om du inte minns lösenordet, använd Återställ lösenordet på inloggningssidan.
• Anläggningen kopplad till ditt konto. Om du loggar in och inte ser din anläggning, be supporten om behörighet.
• Ett program som kan göra webbförfrågningar: Home Assistant, Excel, Python, kommandot curl eller din leverantörs programvara.

Steg 1: skapa en token

1. Gå till ai-care.heiwit.com och logga in.
2. Om du har flera anläggningar, välj den du är intresserad av.
3. Öppna Report i menyn.
4. Längst ner på sidan öppnar du rutan Scarica i dati del tuo impianto och sedan avsnittet Accesso via API.
5. Skriv ett namn som påminner dig om vad token används till, till exempel ”Home Assistant”, och tryck på Crea token.
6. Kopiera token direkt och förvara den på ett säkert ställe: den visas bara en gång. Du känner igen den på att den börjar med aic_.

I samma avsnitt finns listan över aktiva tokens för anläggningen, med senaste användning, antal anrop och det datum då de inaktiveras. Med Revoca stänger du av en direkt.

Steg 2: gör din första begäran

Alla förfrågningar utgår från den här adressen:

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

Token skickas i en rubrik (header) i begäran som heter Authorization, föregången av ordet Bearer och ett mellanslag:

Authorization: Bearer aic_IL_TUO_TOKEN

För ett snabbt test räcker terminalen med kommandot curl, som redan finns i Windows 10 och 11, macOS och Linux. Ersätt aic_IL_TUO_TOKEN med din token:

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

I Windows, i PowerShell, skriver du curl.exe i stället för curl.

Du behöver inte ange vilken anläggning som ska läsas: det bestäms av token. Svaret ser ut ungefär så här:

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

I det här exemplet producerar panelerna 3 120 W: 1 670 W går till huset och 1 450 W laddar batteriet, som ligger på 64 %. Inget utbyts med elnätet.

Vad du kan läsa

API:t har tre adresser, alla med endast läsbehörighet (GET-förfrågningar):

/status: anläggningen just nu

/energy: historiken

Exempel: data dag för dag för september 2026, endast energi och egenförbrukning.

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"

Parametrarna läggs till i adressen efter frågetecknet, åtskilda med &:

Med granularity=hour täcker en begäran högst 400 dagar: för längre perioder gör du flera begäranden. Med day och month kan du begära hela historiken på en gång.

CSV-filen använder kommatecken som avgränsare och punkt för decimaler, det vanligaste formatet för program. För att öppna den i Excel med svenska inställningar lägger du till &delimiter=semicolon&decimal=comma.

Datagrupperna som du kan begära med fields:

Varje rad börjar med datumet (date), som kompletteras med timmen (hour) i timupplösning; i månadsupplösning anges månaden (month). JSON-svaret i exemplet ser ut så här:

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

Här visas bara de första raderna: i data finns alla 30 dagar (count).

/token: tokenens status

Returnerar tokenens namn, anläggningen, skapandedatum, senaste användning, datumet då den inaktiveras om du inte använder den (expires_at), dagens anrop och gränserna. Det är användbart för att kontrollera att allt fungerar. Även detta anrop räknas mot den dagliga gränsen.

Hur aktuella är uppgifterna

• Aktuell status (/status): växelriktaren skickar en avläsning ungefär var 5:e minut och API:et returnerar den senast mottagna. Det frågar inte växelriktaren i realtid utan läser data som redan samlats in av övervakningen, så dina anrop belastar inte anläggningen.
• Historik (/energy): pågående timme och dag är ofullständiga och växer efter hand. Datum och tider anges i italiensk tid.
• Om växelriktaren tappar internetanslutningensvarar API:et ändå med den senast mottagna avläsningen: titta på updated_at för att se hur färsk den är.
• Värdena i euro är uppskattningar, beräknade med periodens grossistpris för energi (PUN) och med samma formel som rutorna i AI-Care. De är inte din elräkning.

Regler och gränser för token

• En token, en anläggning. Om du har flera anläggningar skapar du en token för var och en.
• Endast läsning. Med token kan ingenting ändras.
• Upp till 5 aktiva token per anläggning. Det lönar sig att använda en per program: om du behöver stänga av en fortsätter de andra att fungera.
• 10 anrop per minut och 300 per dag för varje token. Dagsräkningen nollställs vid midnatt, italiensk tid. Varje svar anger dagsgränsen i rubriken X-Quota-Limit och antalet återstående anrop i dag i X-Quota-Remaining.
• Inget fast utgångsdatum. Token inaktiveras automatiskt om den inte används på 60 dagar; varje anrop skjuter fram utgångsdatumet.
• Omedelbar återkallelse. Med Revoca, på sidan Report, slutar token att fungera direkt.

Hur ofta ska du hämta data? Statusen ändras ungefär var 5:e minut, så tätare anrop ger inga nya data. Ett anrop var 5:e minut blir 288 anrop per dag: det ryms inom gränsen, men lämnar bara 12 lediga. Om du även behöver samma token till annat, välj ett anrop var 10:e minut. För historiken räcker ett anrop per dag.

Om något går fel

När en begäran misslyckas svarar API:et med en kod, en förkortning (error) och ett meddelande på italienska som förklarar vad som ska rättas. Till exempel:

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

Färdiga exempel

Home Assistant

Med RESTful-integrationen i Home Assistant kan du skapa sensorer som läser /status. I filen secrets.yaml sparar du token, med ordet Bearer framför:

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Lägg sedan till i 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

Med scan_interval: 600 Home Assistant anropar API:et var 10:e minut: 144 anrop per dag. De övriga totalerna i lifetime_kwh (inmatning, uttag, batteri) läggs till på samma sätt som sensorn ”producerad energi” och kan användas i Energi-instrumentpanelen.

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. I Excel öppnar du Data › Från webb och väljer Avancerat.
2. Klistra in som adress:
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. I HTTP-begärans rubriker skriver du Authorization och bredvid Bearer aic_IL_TUO_TOKEN.
4. Om Excel frågar hur du vill logga in, välj Anonym: auktoriseringen finns redan i rubriken.
5. Läs in tabellen. Från och med då Uppdatera alla läser in den på nytt med nya data.

Utan from och to får du alltid de senaste 30 dagarna. Observera: token förblir sparad i filen, och den som får filen kan läsa anläggningens data.

För installatörer och företag

• En token per anläggning. Med installatörens huvudkonto ser du i AI-Care de anläggningar du följer, och för varje anläggning kan du skapa en token från sidan Report. Gränser och utgångsdatum gäller per token: med 40 anläggningar har du 40 token, var och en med sina 300 anrop per dag.
• Agentkonton ser inte avsnittet Accesso via API (Åtkomst via API): installatörens huvudkonto krävs.
• Uppgifterna tillhör kunden. Använd dem för de tjänster ni har kommit överens om. Kunden ser på sin sida Report alla aktiva token för sin anläggning, även de du har skapat, med namn och senaste användning, och kan återkalla dem. Ge dina token tydliga namn, till exempel ”Underhåll Rossi Impianti”.
• Om en kund vill anförtro dig sina data (artikel 5 i Data Act) är det enklaste att kunden själv skapar en särskild token och lämnar den till dig. Kunden kan återkalla den när samarbetet upphör.

Detsamma gäller mjukvaruföretag, energikonsulter och energigemenskaper: de ansluter med en token per anläggning, som innehavaren skapar och lämnar till dem.

Säkerhet: vad detta API inte gör

• Det lämnar inte ut administratörsuppgifter för växelriktaren.
• Det ändrar inte firmware, elektriska parametrar eller skyddsinställningar: det bara läser.
• Token öppnar inte ditt AI-Care-konto och ger inte åtkomst till andra anläggningar.

Behandla ändå token som ett lösenord: publicera den inte på nätet, lämna den inte i delade filer och skicka den inte i chatt. Om du misstänker att någon har sett den, återkalla den och skapa en ny. Heiwit sparar bara ett fingeravtryck (hash) av token, inte själva token: därför kan ingen, inte ens supporten, skicka den till dig igen. Kommunikationen med API:et är krypterad (HTTPS).

Vanliga frågor och svar

Vad kostar det?

Ingenting. Åtkomsten till de data du har rätt till är kostnadsfri.

Kan jag ändra växelriktarens inställningar med API:et?

Nej. API:et är skrivskyddat: det rör inte firmware, elektriska parametrar eller skydd.

Kan jag ge mina data till installatören eller ett annat företag?

Ja. Data Act ger dig rätt att låta dem göras tillgängliga för en tredje part som du har utsett. I praktiken skapar du en token med ett igenkännbart namn och lämnar den till den du har valt; du kan återkalla den när du vill. För andra förfrågningar, skriv till supporten.

Jag har tappat bort min token. Kan ni skicka den igen?

Nej, eftersom Heiwit inte sparar den. Skapa en ny och återkalla den gamla.

Upphör token att gälla?

Bara om du inte använder den: efter 60 dagar utan anrop inaktiveras den automatiskt. Så länge du använder den förblir den aktiv.

Kan jag läsa flera anläggningar med en enda token?

Nej, varje token gäller för en anläggning. För flera anläggningar behövs flera tokens.

Är värdena i euro samma som på elräkningen?

Nej. Det är uppskattningar beräknade med periodens grossistpris på el (PUN).

Hur långt tillbaka i tiden kan jag gå?

Ända till början av de data som registrerats av övervakningen. Med timupplösning omfattar varje förfrågan högst 400 dagar.

Fungerar det med Home Assistant?

Ja, med RESTful-integrationen: konfigurationen finns i exemplen ovan.

Användbara länkar

• API-dokumentation och förteckning över tillgängliga data: ai-care.heiwit.com/report (efter inloggning, rutan Scarica i dati del tuo impianto (Ladda ner data från din anläggning) › Accesso via API (Åtkomst via API)).
• Aktivering av åtkomst och support: ai-care.heiwit.com/login.
• Videoguide: Heiwit-växelriktare: så får du tillgång till dina data via API.

Rättsliga hänvisningar: Europaparlamentets och rådets förordning (EU) 2023/2854 av den 13 december 2023 (dataakten, Data Act), särskilt artikel 4 om användarens tillgång till data och artikel 5 om delning av data med tredje part. Tillgången till de data som användaren har rätt till är kostnadsfri, efter kontroll av den sökandes behörighet; tillhandahållande av data till en tredje part som användaren har utsett sker på de villkor som anges i förordningen. De tekniska uppgifterna avser version 1 av API:et (/api/v1) per den 5 oktober 2026.

API:et läser de data som samlas in av AI-Care, Heiwits plattform för övervakning av anläggningar. Hjärtat i anläggningen ärhybridväxelriktaren Virgo, i kombination med Heiwits natriumjonbatteri på 10 kWh.