Falar com o hub por HTTP

⚠️ Esta página trata do firmware autónomo do hub. Um hub a correr o pacote ESPHome não tem API REST, nem WebSocket, nem MQTT — é um dispositivo ESPHome, e o Home Assistant comunica com ele através do painel RBgrid e da ação rbgrid_cmd. Tudo o que está abaixo assume que o hub serve a sua própria aplicação web. → Executar dentro do Home Assistant

Tudo o que a aplicação faz, faz por HTTP contra o hub na sua própria rede. Não há nuvem no caminho nem conta: se consegue alcançar o hub, consegue lê-lo, e com o seu token consegue alterá-lo.

Esta página trata da parte que uma tabela de rotas não consegue dizer — que token usar, com que frequência perguntar, e os poucos erros que parecem avarias do hub e não o são. As próprias rotas estão na referência da API gerada, um ficheiro no repositório que o hub produz a partir do seu próprio esquema e que é regenerado a cada versão. Nada aqui repete essa lista, de propósito: uma tabela de rotas copiada à mão fica errada uma versão depois, e fica errada em silêncio.

Os dois tokens

Token	Para que serve
admin	alterar o hub. Depois de definido, toda a escrita o exige — e o hub responde `Admin token required.` quando falta
read	ler o hub, quando tiver um definido

Defina-os na aplicação, em Settings → Security. Enquanto não houver um token de administrador, qualquer pessoa que consiga alcançar o hub pode alterá-lo — por isso a aplicação mantém um aviso no ecrã até que isso e a palavra-passe do ponto de acesso estejam feitos. → Definições

Envie um token como token de portador no pedido. A referência gerada assinala cada rota que exige o token de administrador para escrita.

⚠️ O que a referência gerada não lhe diz é quais as leituras que exigem o token de leitura — ela próprio o diz no cabeçalho. A regra que a aplicação segue é: quando o hub tem os dois tokens definidos, as leituras também exigem o token de leitura. Se está a construir algo que apenas lê, defina um token de leitura e envie-o; um 401 numa rota que esperava aberta quase sempre significa isso.

Para as cinco rotas de preço a divisão está indicada: GET usa o token de leitura, POST usa o token de administrador. Por isso, um painel que apenas lê preços e o registo de preços aplicados nunca precisa do de administrador — e não deve recebê-lo.

Um cliente de navegador não deve levar um token num URL

Numa página que abre um WebSocket, pôr um token no endereço é a forma como os tokens acabam em registos, histórico e capturas de ecrã. O hub tem uma saída: POST /api/v1/ws-ticket devolve um bilhete de uso único, válido por 30 segundos, que o socket apresenta em vez do token. → Dados em tempo real por WebSocket

Permitir que um navegador de outra origem chame o hub

Uma página servida de outro sítio é bloqueada pelo navegador, não pelo hub. /api/system/security é onde permite uma origem — até oito. É uma porta deliberada, por isso abra-a apenas para as origens que usa e para mais nenhumas.

O que consultar, e o que não consultar

Não consulte em ciclo os valores em tempo real. O hub envia-os por iniciativa própria: por WebSocket e por MQTT, à cadência do próprio hub. Consultar /api/v1/summary num ciclo dá-lhe os mesmos números mais tarde, custa ao hub trabalho que ele poderia gastar a medir, e dá-lhe um intervalo de amostragem que se desvia do do hub.

Consulte as coisas que mudam devagar, e ajuste a frequência à velocidade com que mudam de facto:

O quê	Muda	Pergunte
registos do histórico	quando um período fecha	no máximo uma vez por período; por `from`/`to`, e não relendo o dia inteiro
economia	com os registos por trás	o mesmo
o estado do preço	quando os preços chegam ou um estado muda	a notificação de preço é um estado a que pode subscrever; ver abaixo
configuração	quando a altera	depois de a alterar

⚠️ Um ciclo sem recuo é o único padrão que lhe vai custar um fim de semana. Se uma rota falha, a resposta honesta é esperar mais antes da tentativa seguinte, e não tentar com mais força. O hub é um microcontrolador que serve uma aplicação web, uma ligação ao broker, o ciclo de medição e o próprio utilizador ao mesmo tempo; um cliente que martela em nova tentativa apertada é indistinguível, do lado do hub, de um cliente que o faz de propósito.

Ler o que o hub mediu

O histórico é por ponto e por período, e são os mesmos dados que a página Histórico da aplicação mostra — incluindo a qualidade de cada registo, que é a parte que os integradores mais vezes deixam cair e depois não conseguem explicar um valor. Um registo traz bits que indicam se é parcial, recalculado, estimado, ou se cobre uma interrupção. Transporte-os para tudo o que construir; um número cuja qualidade descartou é um número que não consegue defender. → Histórico

A economia é custo e valor de exportação, calculados pelo hub com o preço em vigor para cada período — e não recalculados a partir de uma taxa atual. → Como o custo é calculado

export.csv dá-lhe o mesmo em formato de ficheiro, por ponto, período e tipo. Para qualquer coisa que queira uma folha de cálculo ou um arquivo longo, este é o caminho mais barato: um pedido em vez de um ciclo.

⚠️ O histórico horário é guardado durante 60 dias, depois passa a diário, mensal e anual. Se precisar das horas de um período de faturação completo depois do facto, recolha-as antes de se perderem — um export.csv agendado é a forma habitual.

As rotas de preço (firmware 1.2.0 e posteriores)

Três rotas, e respondem a três perguntas diferentes:

Rota	Responde
`/api/v1/dynprice`	como a fixação de preço está configurada, que fornecedores existem, e o estado em tempo real
`/api/v1/price`	o preço resolvido por período de 15 minutos — e com `log=1`, a que foi efetivamente registado cada período fechado, durante 40 dias
`/api/v1/signal`	a notificação de preço atual: o preço agora, a sua origem, a posição do período no dia, quais as janelas baratas abertas, e as duas bandeiras

/api/v1/price é também uma escrita. Um cliente que conhece os seus preços — uma integração do Home Assistant, o seu próprio script — pode enviar até 200 períodos para o hub, e o hub calcula a energia com eles. É o caminho para um fornecedor para o qual o hub não tem fonte. Indica se o que envia é um preço spot ou um preço tudo incluído; errar nisso é o erro mais caro que existe aqui, porque multiplica silenciosamente todos os valores de custo. → De onde vem o seu preço

Para a notificação, prefira o tópico MQTT retido a consultar /api/v1/signal. É um estado: o hub republica-o a cada limite de 15 minutos e no momento em que algo muda, e uma mensagem retida envia o estado atual a um cliente que se ligue mais tarde. Quem consulta obtém o mesmo, mas com atraso, e só não perde nada se perguntar constantemente. → Saber quando a energia está mais barata

Alterar coisas

As escritas exigem o token de administrador e, em algumas rotas, precisam de um reinício para se aplicarem — a referência gerada tem uma coluna a indicar quais. Algumas regras que não estão em nenhuma tabela:

Uma escrita recusada indica o campo. O hub responde 400 com o campo que não aceitou, o que é muito mais útil do que um código de estado. Leia-o: costuma estar a dizer-lhe algo verdadeiro sobre a sua configuração, como uma zona de preço cuja moeda não é a do seu plano.
Os nomes são limitados em bytes, não em caracteres — 24 bytes para um nome curto, 31 para um nome. Uma letra cirílica ou acentuada ocupa dois, por isso um nome que parece curto pode ainda assim ser recusado.
Em algumas rotas, a configuração é um documento inteiro. Quando uma rota recebe uma secção de configuração, enviar uma secção parcial substitui a secção. Leia-a, altere o que pretende alterar, e envie-a de volta.

O que a API não faz

Sem nuvem, sem conta, sem acesso remoto. O hub serve a sua rede. Tudo o que vá além disso é o seu túnel, a sua VPN, a sua responsabilidade.
Não controla nada. Não há nenhuma rota que comute uma carga. O hub mede, calcula o preço e publica; atuar sobre isso é tarefa do que construir. → Saber quando a energia está mais barata
Sem limite de pedidos por rota em que se possa apoiar. A ausência de um não é uma permissão; veja o aviso sobre recuo acima.

Quando uma chamada não faz o que espera: o que verificar

401 numa coisa que funcionava ontem. Entretanto foi definido um token no hub. As leituras exigem o token de leitura quando existem os dois tokens; as escritas exigem o de administrador.

Admin token required. numa escrita que tem a certeza de estar autorizada. O token está definido mas não chega ao hub — verifique se é um token de portador no próprio pedido, e não um parâmetro na consulta.

Um navegador dá erro de CORS, mas o curl funciona bem. É o navegador a recusar, não o hub. Acrescente a sua origem em /api/system/security; há lugar para oito.

Uma escrita devolve 400 e indica um campo que não enviou. Algumas rotas recebem uma secção de configuração inteira. O campo está na secção que substituiu, e não era válido no estado em que o hub se encontra — a mais comum é uma zona cuja moeda não corresponde à do plano.

Uma definição foi guardada mas nada mudou. Algumas rotas precisam de um reinício para se aplicarem; a referência gerada indica quais, numa coluna própria.

O histórico tem lacunas. As lacunas são registos que o hub não tem, não registos que tenha perdido: estava a reiniciar, a atualizar ou sem energia. Os bits de qualidade dos registos vizinhos dizem o que aconteceu. → Histórico

O registo de preços tem menos de 96 linhas para um dia. A mesma causa, o mesmo significado: o registo guarda os períodos em que o hub esteve a funcionar. Um período em falta não é um preço em falta.

Os valores em tempo real chegam devagar, ou fora de sintonia com a aplicação. Está a consultar quando deveria estar a subscrever. → Dados em tempo real por WebSocket

⚠️ Para qualquer trabalho dentro de um quadro elétrico, chame um eletricista qualificado.