Como aceder aos dados do seu inversor Heiwit através de API (Data Act)

Como aceder aos dados do seu inversor Heiwit através de API

Pode ler os dados da sua instalação Heiwit também a partir de um programa externo, através de API. Entra no AI-Care, abre Report › Scarica i dati del tuo impianto › Accesso via API e cria um token: é a chave que o programa usa para pedir os dados. O acesso é gratuito, apenas de leitura e cada token é válido para uma única instalação. É o procedimento que a Heiwit disponibiliza para exercer o acesso aos dados previsto no Data Act europeu (Regulamento UE 2023/2854).

Não consegue ver o vídeo? Veja-o no YouTube.

No vídeo vê o procedimento completo: ativação do acesso, autenticação com o token e primeiro pedido. Abaixo encontra-o explicado passo a passo, com a lista dos dados disponíveis, os limites e alguns exemplos prontos a copiar.

Antes de mais: precisa mesmo da API?

Se só quer os números numa folha de Excel, não. Na página Report do AI-Care existe o painel Scarica i dati del tuo impianto: escolha o período e o detalhe (hora a hora, dia a dia ou mês a mês) e descarregue um ficheiro Excel ou CSV. Não é preciso configurar nada.

A API serve quando quer que os dados cheguem automaticamente a outro programa, sem descarregar ficheiros manualmente. Por exemplo:

• um sistema de domótica como o Home Assistant;
• uma folha de Excel que se atualiza com um clique;
• o software de gestão de uma empresa, o software de um consultor energético ou de uma comunidade de energia;
• um script escrito por si ou pelo seu técnico.

O que é uma API, em palavras simples

Uma API é um endereço web pensado para programas em vez de pessoas. O utilizador abre uma página e lê-a; um programa “chama” o endereço e recebe os dados num formato organizado, pronto a usar: JSON ou CSV.

Cada chamada leva consigo um token, uma longa chave secreta. Funciona como uma palavra-passe, com duas diferenças: serve apenas para ler os dados e dá acesso a uma única instalação.

O direito aos seus dados: o Data Act

O Data Act é o regulamento europeu sobre dados (Regulamento UE 2023/2854) e aplica-se desde 12 de setembro de 2025. Abrange também os produtos conectados, como o inversor com o seu serviço de monitorização, e confere a quem os utiliza dois direitos:

• aceder aos dados gerados pela utilização do produto e utilizá-los (artigo 4.º);
• disponibilizá-los a um terceiro por si designado, por exemplo o instalador ou um consultor (artigo 5.º).

Por isso, o acesso aos dados a que tem direito é gratuito. Primeiro, a Heiwit verifica se tem direito: é por isso que o token só pode ser criado depois de entrar no AI-Care com a conta à qual a instalação está associada.

O que precisa

• A conta do portal Heiwit. O AI-Care usa as mesmas credenciais do portal: e-mail ou nome de utilizador e palavra-passe. Se não se lembrar da palavra-passe, use Recuperar a palavra-passe na página de acesso.
• A instalação associada à sua conta. Se entrar e não vir a sua instalação, peça a ativação à assistência.
• Um programa capaz de fazer pedidos web: Home Assistant, Excel, Python, o comando curl ou o software do seu fornecedor.

Passo 1: crie o token

1. Aceda a ai-care.heiwit.com e inicie sessão.
2. Se tiver várias instalações, escolha a que lhe interessa.
3. Abra Report no menu.
4. No fundo da página, abra o painel Scarica i dati del tuo impianto e depois a secção Accesso via API.
5. Escreva um nome que lhe lembre para que serve o token, por exemplo “Home Assistant”, e prima Crea token.
6. Copie imediatamente o token e guarde-o num local seguro: é mostrado apenas uma vez. Reconhece-o porque começa por aic_.

Na mesma secção encontra a lista dos tokens ativos na instalação, com a última utilização, o número de chamadas e a data em que serão desativados. Com Revoca desativa um de imediato.

Passo 2: faça o primeiro pedido

Todos os pedidos partem deste endereço:

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

O token é enviado num cabeçalho (header) do pedido chamado Authorization, precedido da palavra Bearer e de um espaço:

Authorization: Bearer aic_IL_TUO_TOKEN

Para um teste rápido basta o terminal com o comando curl, já presente no Windows 10 e 11, macOS e Linux. Substitua aic_IL_TUO_TOKEN pelo seu token:

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

No Windows, no PowerShell, escreva curl.exe em vez de curl.

Não precisa de indicar que instalação ler: é o token que o determina. A resposta é semelhante 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
  }
}

Neste exemplo, os painéis produzem 3120 W: 1670 W vão para a casa e 1450 W carregam a bateria, que está a 64%. Não há qualquer troca com a rede.

O que pode ler

A API tem três endereços, todos apenas de leitura (pedidos GET):

/status: a instalação agora

/energy: o histórico

Exemplo: os dados dia a dia de setembro de 2026, apenas energia e 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"

Os parâmetros acrescentam-se ao endereço depois do ponto de interrogação, separados por &:

Com granularity=hour um pedido abrange no máximo 400 dias: para períodos mais longos, faça vários pedidos. Com day e month pode pedir todo o histórico de uma só vez.

O CSV usa a vírgula como separador e o ponto para as casas decimais, o formato mais comum para os programas. Para o abrir no Excel em italiano, acrescente &delimiter=semicolon&decimal=comma.

Os grupos de dados que pode pedir com fields:

Cada linha começa com a data (date), à qual se acrescenta a hora (hour) no detalhe horário; no detalhe mensal, aparece o mês (month). A resposta JSON do exemplo tem este aspeto:

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

Aqui são mostradas apenas as primeiras linhas: em data estão todos os 30 dias (count).

/token: o estado do token

Devolve o nome do token, o sistema, a data de criação, a última utilização, a data em que será desativado se não o usar (expires_at), as chamadas feitas hoje e os limites. É útil para verificar se tudo funciona. Esta chamada também conta para o limite diário.

Qual a atualização dos dados

• Estado atual (/status): o inversor envia uma leitura aproximadamente a cada 5 minutos e a API devolve a última recebida. Não consulta o inversor em direto: lê os dados já recolhidos pela monitorização, pelo que as suas chamadas não sobrecarregam o sistema.
• Histórico (/energy): a hora e o dia em curso são parciais e vão aumentando. As datas e horas são as de Itália.
• Se o inversor perder a ligação à internet, a API responde mesmo assim com a última leitura recebida: consulte updated_at para perceber se é recente.
• Os valores em euros são estimativas, calculadas com o preço grossista da energia (PUN) do período e com a mesma fórmula dos painéis do AI-Care. Não correspondem à sua fatura.

Regras e limites do token

• Um token, um sistema. Se tiver vários sistemas, crie um token para cada um.
• Apenas leitura. Com o token não é possível alterar nada.
• Até 5 tokens ativos por instalação. É aconselhável usar um para cada programa: se tiver de desativar um, os outros continuam a funcionar.
• 10 chamadas por minuto e 300 por dia para cada token. A contagem diária recomeça à meia-noite, hora italiana. Cada resposta indica o limite diário no cabeçalho X-Quota-Limit e as chamadas restantes hoje em X-Quota-Remaining.
• Sem prazo de validade fixo. O token desativa-se automaticamente se ficar sem utilização durante 60 dias; cada chamada adia a data de expiração.
• Revogação imediata. Com Revoca, na página Report, o token deixa de funcionar imediatamente.

Com que frequência pedir os dados? O estado muda aproximadamente a cada 5 minutos, por isso chamar com mais frequência não dá dados novos. Uma chamada a cada 5 minutos dá 288 chamadas por dia: fica dentro do limite, mas deixa livres apenas 12. Se precisar do mesmo token também para outras coisas, opte por uma chamada a cada 10 minutos. Para o histórico basta uma chamada por dia.

Se algo correr mal

Quando um pedido não é bem-sucedido, a API responde com um código, uma sigla (error) e uma mensagem em italiano que explica o que corrigir. Por exemplo:

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

Exemplos prontos a usar

Home Assistant

Com a integração RESTful do Home Assistant pode criar sensores que leem /status. No ficheiro secrets.yaml guarde o token, com a palavra Bearer à frente:

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Depois adicione em 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

Com scan_interval: 600 O Home Assistant chama a API a cada 10 minutos: 144 chamadas por dia. Os outros totais de lifetime_kwh (injeção, consumo da rede, bateria) adicionam-se tal como o sensor “energia produzida” e podem ser usados no painel Energia.

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. No Excel abra Dados › Da Web e escolha Avançadas.
2. Como endereço, cole:
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. Nos cabeçalhos do pedido HTTP escreva Authorization e, ao lado, Bearer aic_IL_TUO_TOKEN.
4. Se o Excel perguntar como aceder, escolha Anónimo: a autorização já está no cabeçalho.
5. Carregue a tabela. A partir desse momento, Atualizar tudo volta a carregá-la com os dados novos.

Sem from e to recebe sempre os últimos 30 dias. Atenção: o token fica guardado no ficheiro, e quem receber o ficheiro pode ler os dados da instalação.

Para instaladores e empresas

• Um token por instalação. Com a conta principal do instalador vê no AI-Care as instalações que acompanha e, para cada uma, pode criar um token a partir da página Report. Os limites e a expiração aplicam-se token a token: com 40 instalações tem 40 tokens, cada um com as suas 300 chamadas por dia.
• As contas de agente não veem a secção Accesso via API (Acesso por API): é necessária a conta principal do instalador.
• Os dados pertencem ao cliente. Utilize-os para os serviços acordados com ele. O cliente vê na sua página Report todos os tokens ativos na sua instalação, incluindo os criados por si, com nome e última utilização, e pode revogá-los. Dê aos tokens nomes claros, por exemplo “Manutenção Rossi Instalações”.
• Se um cliente quiser confiar-lhe os seus dados (artigo 5.º do Data Act), o caminho mais simples é ele criar um token dedicado e entregar-lho. Poderá revogá-lo quando a relação terminar.

O mesmo se aplica a empresas de software, consultores energéticos e comunidades de energia: ligam-se com um token por instalação, que o titular cria e lhes entrega.

Segurança: o que esta API não faz

• Não fornece credenciais de administração do inversor.
• Não altera firmware, parâmetros elétricos nem definições de proteção: apenas lê.
• O token não abre a sua conta AI-Care nem dá acesso a outras instalações.

Ainda assim, trate o token como uma palavra-passe: não o publique online, não o deixe em ficheiros partilhados, não o envie por chat. Se suspeitar que alguém o viu, revogue-o e crie um novo. A Heiwit guarda apenas uma impressão digital (hash) do token, não o token em si: por isso ninguém, nem mesmo a assistência, lho pode reenviar. As comunicações com a API são cifradas (HTTPS).

Perguntas mais frequentes

Quanto custa?

Nada. O acesso aos dados a que tem direito é gratuito.

Com a API posso alterar as definições do inversor?

Não. A API é apenas de leitura: não mexe no firmware, nos parâmetros elétricos nem nas proteções.

Posso dar os meus dados ao instalador ou a outra empresa?

Sim. O Data Act permite-lhe disponibilizá-los a um terceiro por si designado. Na prática, cria um token com um nome reconhecível e entrega-o a quem escolheu; pode revogá-lo quando quiser. Para outros pedidos, escreva à assistência.

Perdi o token. Podem reenviar-mo?

Não, porque a Heiwit não o guarda. Crie um novo e revogue o antigo.

O token expira?

Apenas se não o utilizar: após 60 dias sem chamadas, desativa-se automaticamente. Enquanto o utilizar, permanece ativo.

Posso consultar várias instalações com um único token?

Não, cada token é válido para uma instalação. Para várias instalações são necessários vários tokens.

Os valores em euros são os da fatura?

Não. São estimativas calculadas com o preço da energia no mercado grossista (PUN) do período.

Até quando posso recuar no tempo?

Até ao início dos dados registados pela monitorização. Com o detalhe horário, cada pedido abrange no máximo 400 dias.

Funciona com o Home Assistant?

Sim, com a integração RESTful: encontra a configuração nos exemplos acima.

Links úteis

• Documentação da API e lista dos dados acessíveis: ai-care.heiwit.com/report (após o início de sessão, painel Scarica i dati del tuo impianto (Descarregue os dados da sua instalação) › Accesso via API (Acesso por API)).
• Ativação do acesso e assistência: ai-care.heiwit.com/login.
• Vídeo tutorial: Inversor Heiwit: como aceder aos seus dados através de API.

Referências normativas: Regulamento (UE) 2023/2854 do Parlamento Europeu e do Conselho, de 13 de dezembro de 2023 (Data Act), em particular o artigo 4.º, sobre o acesso do utilizador aos dados, e o artigo 5.º, sobre a sua partilha com terceiros. O acesso aos dados a que o utilizador tem direito é gratuito, mediante verificação da legitimidade do requerente; a disponibilização dos dados a um terceiro designado pelo utilizador realiza-se nas condições previstas no regulamento. As indicações técnicas referem-se à versão 1 da API (/api/v1) a 5 de outubro de 2026.

A API lê os dados recolhidos pela AI-Care, a plataforma Heiwit de monitorização das instalações. O coração da instalação é oinversor híbrido Virgo, combinado com a bateria Heiwit de iões de sódio de 10 kWh.