Comment accéder aux données de votre onduleur Heiwit via API (Data Act)

Comment accéder aux données de votre onduleur Heiwit via API

Vous pouvez aussi lire les données de votre installation Heiwit depuis un programme externe, via API. Connectez-vous à AI-Care, ouvrez Report › Scarica i dati del tuo impianto (Téléchargez les données de votre installation) › Accesso via API (Accès via API) et créez un jeton : c’est la clé que le programme utilise pour demander les données. L’accès est gratuit, en lecture seule, et chaque jeton est valable pour une seule installation. C’est la procédure que Heiwit met à disposition pour exercer l’accès aux données prévu par le Data Act européen (Règlement UE 2023/2854).

La vidéo ne s’affiche pas ? Regardez-la sur YouTube.

La vidéo présente la procédure complète : activation de l’accès, authentification avec le jeton et première requête. Vous la trouverez ci-dessous expliquée étape par étape, avec la liste des données disponibles, les limites et quelques exemples prêts à copier.

Avant tout : avez-vous vraiment besoin de l’API ?

Si vous voulez seulement les chiffres dans une feuille Excel, non. Sur la page Report d’AI-Care se trouve l’encadré Scarica i dati del tuo impianto: choisissez la période et le niveau de détail (heure par heure, jour par jour ou mois par mois) et téléchargez un fichier Excel ou CSV. Aucune configuration n’est nécessaire.

L’API est utile lorsque vous voulez que les données arrivent automatiquement dans un autre programme, sans télécharger de fichiers à la main. Par exemple :

• un système domotique comme Home Assistant;
• une feuille Excel qui se met à jour en un clic ;
• le logiciel de gestion d’une entreprise, le logiciel d’un conseiller en énergie ou d’une communauté énergétique ;
• un script écrit par vous ou par votre technicien.

Qu’est-ce qu’une API, en termes simples

Une API est une adresse web conçue pour les programmes plutôt que pour les personnes. Vous ouvrez une page et la lisez ; un programme « appelle » l’adresse et reçoit les données dans un format ordonné, prêt à l’emploi : JSON ou CSV.

Chaque appel transporte un jeton, une longue clé secrète. Il fonctionne comme un mot de passe, avec deux différences : il sert uniquement à lire les données et n’ouvre qu’une seule installation.

Le droit à vos données : le Data Act

Le Data Act est le règlement européen sur les données (Règlement UE 2023/2854) et s’applique depuis le 12 septembre 2025. Il concerne aussi les produits connectés, comme l’onduleur avec son service de surveillance, et confère à leurs utilisateurs deux droits :

• accéder aux données générées par l’utilisation du produit et les utiliser (article 4) ;
• les faire mettre à disposition d’un tiers mandaté par lui, par exemple l’installateur ou un conseiller (article 5).

C’est pourquoi l’accès aux données qui vous reviennent est gratuit. Heiwit vérifie d’abord que vous y avez droit : c’est pourquoi le jeton ne peut être créé qu’après connexion à AI-Care avec le compte auquel l’installation est associée.

Ce dont vous avez besoin

• Le compte du portail Heiwit. AI-Care utilise les mêmes identifiants que le portail : e-mail ou nom d’utilisateur et mot de passe. Si vous avez oublié votre mot de passe, utilisez Récupérer le mot de passe sur la page de connexion.
• L’installation associée à votre compte. Si vous vous connectez et ne voyez pas votre installation, demandez l’activation à l’assistance.
• Un programme capable d’envoyer des requêtes web: Home Assistant, Excel, Python, la commande curl ou le logiciel de votre fournisseur.

Étape 1 : créez le jeton

1. Rendez-vous sur ai-care.heiwit.com et connectez-vous.
2. Si vous avez plusieurs installations, choisissez celle qui vous intéresse.
3. Ouvrez Report depuis le menu.
4. En bas de la page, ouvrez l’encadré Scarica i dati del tuo impianto puis la section Accesso via API.
5. Saisissez un nom qui vous rappelle à quoi sert le jeton, par exemple « Home Assistant », et cliquez sur Crea token.
6. Copiez immédiatement le jeton et conservez-le en lieu sûr : il n’est affiché qu’une seule fois. Vous le reconnaîtrez car il commence par aic_.

Dans la même section se trouve la liste des jetons actifs sur l’installation, avec leur dernière utilisation, le nombre d’appels et la date à laquelle ils seront désactivés. Avec Revoca vous en désactivez un instantanément.

Étape 2 : effectuez la première requête

Toutes les requêtes partent de cette adresse :

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

Le jeton s’envoie dans un en-tête (header) de la requête appelé Authorization, précédé du mot Bearer et d’une espace :

Authorization: Bearer aic_IL_TUO_TOKEN

Pour un test rapide, le terminal suffit avec la commande curl, déjà présente sous Windows 10 et 11, macOS et Linux. Remplacez aic_IL_TUO_TOKEN par votre jeton :

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

Sous Windows, dans PowerShell, saisissez curl.exe au lieu de curl.

Vous n’avez pas à indiquer quelle installation lire : c’est le jeton qui le détermine. La réponse ressemble à celle-ci :

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

Dans cet exemple, les panneaux produisent 3 120 W : 1 670 W vont à la maison et 1 450 W chargent la batterie, qui est à 64 %. Aucun échange avec le réseau.

Ce que vous pouvez lire

L’API dispose de trois adresses, toutes en lecture seule (requêtes GET) :

/status : l’installation en ce moment

/energy : l’historique

Exemple : les données jour par jour de septembre 2026, uniquement énergie et autoconsommation.

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"

Les paramètres s’ajoutent à l’adresse après le point d’interrogation, séparés par &:

Avec granularity=hour une requête couvre au maximum 400 jours : pour des périodes plus longues, effectuez plusieurs requêtes. Avec day et month vous pouvez demander tout l’historique en une seule fois.

Le CSV utilise la virgule comme séparateur et le point pour les décimales, le format le plus courant pour les logiciels. Pour l’ouvrir avec Excel en français, ajoutez &delimiter=semicolon&decimal=comma.

Les groupes de données que vous pouvez demander avec fields:

Chaque ligne commence par la date (date), à laquelle s’ajoute l’heure (hour) dans le détail horaire ; dans le détail mensuel figure le mois (month). La réponse JSON de l’exemple se présente ainsi :

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

Seules les premières lignes sont affichées ici : dans data figurent les 30 jours (count).

/token : l’état du token

Renvoie le nom du token, l’installation, la date de création, la dernière utilisation, la date à laquelle il se désactivera si vous ne l’utilisez pas (expires_at), les appels effectués aujourd’hui et les limites. C’est utile pour vérifier que tout fonctionne. Cet appel est lui aussi décompté de la limite journalière.

Fraîcheur des données

• État actuel (/status) : l’onduleur envoie un relevé environ toutes les 5 minutes et l’API renvoie le dernier reçu. Elle n’interroge pas l’onduleur en direct : elle lit les données déjà collectées par le monitoring, vos appels ne sollicitent donc pas l’installation.
• Historique (/energy) : l’heure et le jour en cours sont partiels et augmentent progressivement. Les dates et heures sont celles de l’Italie.
• Si l’onduleur perd la connexion Internet, l’API répond quand même avec le dernier relevé reçu : consultez updated_at pour savoir s’il est récent.
• Les valeurs en euros sont des estimations, calculées avec le prix de gros de l’énergie (PUN) de la période et avec la même formule que les encadrés d’AI-Care. Il ne s’agit pas de votre facture.

Règles et limites du token

• Un token, une installation. Si vous avez plusieurs installations, créez un token pour chacune.
• Lecture seule. Le token ne permet de rien modifier.
• Jusqu'à 5 tokens actifs par installation. Il est conseillé d'en utiliser un par programme : si vous devez en désactiver un, les autres continuent de fonctionner.
• 10 appels par minute et 300 par jour pour chaque token. Le décompte journalier repart à zéro à minuit, heure italienne. Chaque réponse indique la limite journalière dans l'en-tête X-Quota-Limit et les appels restants pour la journée dans X-Quota-Remaining.
• Aucune échéance fixe. Le token se désactive automatiquement s'il reste inutilisé pendant 60 jours ; chaque appel repousse l'échéance.
• Révocation immédiate. Avec Revoca, dans la page Report, le token cesse immédiatement de fonctionner.

À quelle fréquence demander les données ? L'état change environ toutes les 5 minutes : appeler plus souvent ne fournit donc pas de nouvelles données. Un appel toutes les 5 minutes représente 288 appels par jour : cela reste dans la limite, mais n'en laisse que 12 de libres. Si vous utilisez aussi le même token pour autre chose, optez pour un appel toutes les 10 minutes. Pour l'historique, un appel par jour suffit.

En cas de problème

Lorsqu'une requête échoue, l'API répond avec un code, un identifiant (error) et un message en italien qui explique ce qu'il faut corriger. Par exemple :

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

Exemples prêts à l'emploi

Home Assistant

Avec l'intégration RESTful de Home Assistant, vous pouvez créer des capteurs qui lisent /status. Dans le fichier secrets.yaml enregistrez le token, précédé du mot Bearer :

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Ajoutez ensuite dans 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

Avec scan_interval: 600 Home Assistant appelle l'API toutes les 10 minutes : 144 appels par jour. Les autres totaux de lifetime_kwh (injection, soutirage, batterie) s'ajoutent comme le capteur « énergie produite » et peuvent être utilisés dans le tableau de bord Énergie.

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. Dans Excel, ouvrez Données › À partir du web et choisissez Avancé.
2. Comme adresse, collez :
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. Dans les en-têtes de la requête HTTP, saisissez Authorization et, à côté, Bearer aic_IL_TUO_TOKEN.
4. Si Excel demande comment se connecter, choisissez Anonyme: l'autorisation figure déjà dans l'en-tête.
5. Chargez le tableau. À partir de ce moment, Actualiser tout le recharge avec les nouvelles données.

Sans from et to vous recevez toujours les 30 derniers jours. Attention : le token reste enregistré dans le fichier, et quiconque reçoit le fichier peut lire les données de l'installation.

Pour les installateurs et les entreprises

• Un token par installation. Avec le compte principal de l'installateur, vous voyez dans AI-Care les installations que vous suivez, et pour chacune vous pouvez créer un token depuis la page Report. Les limites et l'échéance s'appliquent token par token : avec 40 installations, vous avez 40 tokens, chacun avec ses 300 appels par jour.
• Les comptes agents ne voient pas la section Accesso via API (Accès via API): le compte principal de l'installateur est nécessaire.
• Les données appartiennent au client. Utilisez-les pour les services convenus avec lui. Le client voit dans sa page Report tous les tokens actifs sur son installation, y compris ceux que vous avez créés, avec leur nom et leur dernière utilisation, et peut les révoquer. Donnez aux tokens des noms clairs, par exemple « Maintenance Rossi Impianti ».
• Si un client souhaite vous confier ses données (article 5 du Data Act), le plus simple est qu'il crée lui-même un token dédié et vous le remette. Il pourra le révoquer à la fin de la relation.

Il en va de même pour les éditeurs de logiciels, les consultants en énergie et les communautés énergétiques : ils se connectent avec un token par installation, que le titulaire crée et leur remet.

Sécurité : ce que cette API ne fait pas

• Elle ne fournit pas d'identifiants d'administration de l'onduleur.
• Elle ne modifie ni le firmware, ni les paramètres électriques, ni les réglages de protection : elle se contente de lire.
• Le token n'ouvre pas votre compte AI-Care et ne donne pas accès à d'autres installations.

Traitez néanmoins le token comme un mot de passe : ne le publiez pas en ligne, ne le laissez pas dans des fichiers partagés, ne l'envoyez pas par messagerie instantanée. Si vous craignez que quelqu'un l'ait vu, révoquez-le et créez-en un nouveau. Heiwit ne conserve qu'une empreinte (hash) du token, pas le token lui-même : c'est pourquoi personne, pas même l'assistance, ne peut vous le renvoyer. Les communications avec l'API sont chiffrées (HTTPS).

Questions fréquemment posées

Combien ça coûte ?

Rien. L'accès aux données qui vous reviennent est gratuit.

Puis-je modifier les réglages de l'onduleur avec l'API ?

Non. L'API est en lecture seule : elle ne touche ni au firmware, ni aux paramètres électriques, ni aux protections.

Puis-je transmettre mes données à l'installateur ou à une autre entreprise ?

Oui. Le Data Act vous permet de les faire mettre à la disposition d'un tiers que vous avez mandaté. En pratique, vous créez un token avec un nom reconnaissable et vous le remettez à la personne choisie ; vous pouvez le révoquer à tout moment. Pour d'autres demandes, écrivez à l'assistance.

J'ai perdu le token. Pouvez-vous me le renvoyer ?

Non, car Heiwit ne le conserve pas. Créez-en un nouveau et révoquez l'ancien.

Le token expire-t-il ?

Seulement si vous ne l'utilisez pas : après 60 jours sans appel, il se désactive automatiquement. Tant que vous l'utilisez, il reste actif.

Puis-je consulter plusieurs installations avec un seul token ?

Non, chaque token est valable pour une seule installation. Pour plusieurs installations, il faut plusieurs tokens.

Les montants en euros correspondent-ils à ceux de la facture ?

Non. Il s'agit d'estimations calculées à partir du prix de gros de l'électricité (PUN) de la période.

Jusqu'à quand puis-je remonter dans le temps ?

Jusqu'au début des données enregistrées par la surveillance. Avec le détail horaire, chaque requête couvre au maximum 400 jours.

Est-ce compatible avec Home Assistant ?

Oui, avec l'intégration RESTful : vous trouverez la configuration dans les exemples ci-dessus.

Liens utiles

• Documentation de l'API et liste des données accessibles: ai-care.heiwit.com/report (après connexion, encadré Scarica i dati del tuo impianto (Téléchargez les données de votre installation) › Accesso via API (Accès via API)).
• Activation de l'accès et assistance: ai-care.heiwit.com/login.
• Vidéo explicative: Onduleur Heiwit : comment accéder à vos données via API.

Références réglementaires : Règlement (UE) 2023/2854 du Parlement européen et du Conseil du 13 décembre 2023 (Data Act), notamment l'article 4, relatif à l'accès de l'utilisateur aux données, et l'article 5, relatif à leur partage avec des tiers. L'accès aux données auxquelles l'utilisateur a droit est gratuit, sous réserve de vérification de la légitimité du demandeur ; la mise à disposition des données à un tiers mandaté par l'utilisateur s'effectue aux conditions prévues par le règlement. Les indications techniques se réfèrent à la version 1 de l'API (/api/v1) au 5 octobre 2026.

L'API lit les données collectées par AI-Care, la plateforme Heiwit de surveillance des installations. Le cœur de l'installation est l'onduleur hybride Virgo, associé à la batterie Heiwit sodium-ion de 10 kWh.