Hablar con el hub por HTTP

⚠️ Esta página trata del firmware autónomo del hub. Un hub que ejecuta el paquete ESPHome no tiene API REST, ni WebSocket, ni MQTT — es un dispositivo ESPHome, y Home Assistant se comunica con él a través del panel de RBgrid y de la acción rbgrid_cmd. Todo lo que sigue supone que el hub sirve su propia aplicación web. → Run it inside Home Assistant

Todo lo que hace la aplicación lo hace por HTTP contra el hub en su propia red. No hay nube en el camino ni cuenta: si puede llegar al hub, puede leerlo, y con su token puede cambiarlo.

Esta página cubre lo que una tabla de rutas no puede explicar: qué token usar, con qué frecuencia consultar y los pocos errores que parecen fallos del hub y no lo son. Las rutas en sí están en la referencia de API generada, un archivo del repositorio que el hub produce a partir de su propio esquema y que se regenera en cada versión. Aquí no se repite esa lista a propósito: una tabla de rutas copiada a mano queda mal una versión después, y queda mal en silencio.

Los dos tokens

Token	Para qué sirve
admin	cambiar el hub. Una vez configurado, cada escritura lo necesita — y el hub responde `Admin token required.` cuando falta
read	leer el hub, cuando ha configurado uno

Configúrelos en la aplicación, Settings → Security. Mientras no haya un token de administrador, cualquiera que pueda llegar al hub puede cambiarlo — por eso la aplicación mantiene en pantalla un aviso hasta que se completen esto y la contraseña del punto de acceso. → Settings

Envíe un token como token portador en la petición. La referencia generada marca cada ruta que necesita el token de administrador para escribir.

⚠️ Lo que la referencia generada no le dice es qué lecturas necesitan el token de lectura — lo indica en su propia cabecera. La regla que sigue la aplicación es: cuando el hub tiene ambos tokens configurados, las lecturas también necesitan el token de lectura. Si está construyendo algo que solo lee, configure un token de lectura y envíelo; un 401 en una ruta que esperaba abierta casi siempre significa eso.

Para las cinco rutas de precios la división está indicada: GET usa el token de lectura, POST usa el token de administrador. Así, un panel que solo lee precios y el registro de precios aplicados nunca necesita el de administrador, y no debería dárselo.

Un cliente de navegador no debe llevar un token en una URL

En una página que abre un WebSocket, poner un token en la dirección es la forma en que los tokens acaban en registros, historiales y capturas de pantalla. El hub ofrece una salida: POST /api/v1/ws-ticket devuelve un ticket de un solo uso, válido durante 30 segundos, que el socket presenta en su lugar. → Live data over WebSocket

Permitir que un navegador de otro origen llame al hub

Una página servida desde otro lugar la bloquea el navegador, no el hub. /api/system/security es donde se permite un origen — hasta ocho. Es una puerta deliberada: ábrala solo para los orígenes que usa y para ninguno más.

Qué consultar, y qué no

No consulte los valores en vivo. El hub los envía: por WebSocket y por MQTT, a su propio ritmo. Consultar /api/v1/summary en un bucle le da los mismos números más tarde, le cuesta al hub trabajo que podría dedicar a medir, y le da un intervalo de muestreo que se desvía del del hub.

Consulte lo que cambia despacio, y ajuste la frecuencia a la rapidez con que cambia realmente:

Qué	Cambia	Pida
registros del historial	cuando se cierra un periodo	como máximo una vez por periodo; por `from`/`to`, no releyendo el día completo
economía	con los registros que la sustentan	lo mismo
el estado del precio	cuando llegan precios o cambia un estado	la notificación de precio es un estado al que puede suscribirse; véase abajo
configuración	cuando la cambia	después de cambiarla

⚠️ Un bucle sin espera progresiva es el patrón que le costará un fin de semana. Si una ruta falla, la respuesta honesta es esperar más antes del siguiente intento, no insistir con más fuerza. El hub es un microcontrolador que sirve una aplicación web, una conexión con el broker, el bucle de medición y a usted al mismo tiempo; un cliente que reintenta sin pausa es, desde el lado del hub, indistinguible de un cliente que lo hace a propósito.

Leer lo que el hub ha medido

El historial es por punto y por periodo, y son los mismos datos que muestra la página History de la aplicación — incluida la calidad de cada registro, que es la parte que más suelen omitir los integradores, y luego no pueden explicar una cifra. Un registro lleva bits que indican si es parcial, recalculado, estimado o si cubre un corte. Llévelos hasta lo que construya; un número cuya calidad ha descartado es un número que no puede defender. → History

La economía es el coste y el valor de la exportación, calculados por el hub con el precio vigente en cada periodo — no recalculados con una tarifa actual. → How cost is calculated

export.csv le da lo mismo en forma de archivo, por punto, periodo y tipo. Para cualquier cosa que quiera una hoja de cálculo o un archivo histórico largo, esta es la vía más económica: una petición en lugar de un bucle.

⚠️ El historial horario se conserva 60 días, y después pasa a diario, mensual y anual. Si necesita las horas de un ciclo de facturación completo a posteriori, descárguelas antes de que se agreguen — un export.csv programado es lo habitual.

Las rutas de precios (firmware 1.2.0 y posteriores)

Tres rutas, que responden a tres preguntas distintas:

Ruta	Responde
`/api/v1/dynprice`	cómo está configurado el precio, qué proveedores existen y el estado en vivo
`/api/v1/price`	el precio resuelto por periodo de 15 minutos — y con `log=1`, a qué precio se aplicó realmente cada periodo cerrado, durante 40 días
`/api/v1/signal`	la notificación de precio actual: el precio ahora, su fuente, la posición del periodo en el día, qué ventanas baratas están abiertas, y los dos indicadores

/api/v1/price también es una escritura. Un cliente que conoce sus precios — una integración de Home Assistant, su propio script — puede enviar hasta 200 periodos al hub, y el hub fija el precio de la energía con ellos. Es la vía para un suministrador del que el hub no tiene fuente. Usted indica si lo que envía es un precio spot o un precio all-in; equivocarse en eso es el error más caro que se puede cometer aquí, porque multiplica en silencio cada cifra de coste. → Where your price comes from

Para la notificación, prefiera el tema MQTT retenido en lugar de consultar /api/v1/signal. Es un estado: el hub lo vuelve a publicar en cada límite de periodo de 15 minutos y en el momento en que algo cambia, y un mensaje retenido entrega el estado actual a un cliente que se conecta más tarde. Un sondeo obtiene lo mismo, con retraso, y solo no pierde nada si pregunta constantemente. → Knowing when energy is cheapest

Cambiar cosas

Las escrituras requieren el token de administrador y, en algunas rutas, necesitan un reinicio para aplicarse; la referencia generada tiene una columna que indica cuáles. Algunas reglas que no aparecen en ninguna tabla:

Una escritura rechazada nombra el campo. El hub responde 400 con el campo que no aceptó, lo cual es mucho más útil que un código de estado. Léalo: normalmente le está diciendo algo cierto sobre su configuración, como una zona de precio que cotiza en una moneda que no es la de su plan.
Los nombres se limitan en bytes, no en caracteres — 24 bytes para un nombre corto, 31 para un nombre. Una letra cirílica o acentuada ocupa dos, así que un nombre que parece corto puede ser rechazado.
En algunas rutas la configuración es un documento completo. Cuando una ruta recibe una sección de configuración, enviar una sección parcial sustituye la sección entera. Léala, cambie lo que quiere cambiar y envíela de vuelta.

Lo que la API no hará

Sin nube, sin cuenta, sin acceso remoto. El hub sirve a su red. Cualquier cosa más allá es su túnel, su VPN, su responsabilidad.
No controla nada. No hay ninguna ruta que conmute una carga. El hub mide, fija precios y publica; actuar en consecuencia es tarea de lo que usted construya. → Knowing when energy is cheapest
No hay límite de frecuencia por ruta en el que apoyarse. La ausencia de uno no es permiso; véase la advertencia sobre la espera progresiva.

Cuando una llamada no hace lo que espera: qué comprobar

401 en algo que funcionaba ayer. Desde entonces se configuró un token en el hub. Las lecturas necesitan el token de lectura cuando existen ambos tokens; las escrituras necesitan el de administrador.

Admin token required. en una escritura que está seguro de que está autorizada. El token está configurado pero no llega al hub — compruebe que es un token portador en la propia petición, no un parámetro de la consulta.

Un navegador da un error de CORS, pero curl funciona bien. Es el navegador el que lo rechaza, no el hub. Añada su origen en /api/system/security; hay sitio para ocho.

Una escritura devuelve 400 y nombra un campo que usted no envió. Algunas rutas reciben una sección completa de configuración. El campo está en la sección que sustituyó, y no era válido en el estado en que está el hub — una zona cuya moneda no coincide con la del plan es la más habitual.

Un ajuste se guardó pero no cambió nada. Algunas rutas necesitan un reinicio para aplicarse; la referencia generada indica cuáles en su propia columna.

El historial tiene huecos. Los huecos son registros que el hub no tiene, no registros que haya perdido: estaba reiniciándose, actualizándose o sin corriente. Los bits de calidad de los registros vecinos indican lo que ocurrió. → History

El registro de precios tiene menos de 96 filas para un día. Misma causa, mismo significado: el registro contiene los periodos en los que el hub estaba funcionando. Un periodo que falta no es un precio que falta.

Los valores en vivo llegan lentos, o desfasados respecto a la aplicación. Está consultando donde debería suscribirse. → Live data over WebSocket

⚠️ Para cualquier trabajo dentro de un cuadro eléctrico, llame a un electricista cualificado.