Integración domótica Octopus Energy España, gratuita y de código abierto
Unofficial: Octopus Energy Spain prices by 2.0TD period, hourly use, balances, last bill.
Publicado por LM1LC3N7
- Dispositivos
- Versión 0.1.1
- Requiere Gladys >=5.3.0
- ★ 0
La documentación de esta integración la escribe su autor y, por ahora, solo está disponible en inglés.
Unofficial integration, not affiliated with Octopus Energy, for Octopus
Energy España customers. It reads your account through the official Kraken
GraphQL API of Octopus España (api.oees-kraken.energy) and gives Gladys:
- one device per electricity supply point (CUPS): the price per kWh now and next, the prices of the three 2.0TD periods (taxes included), the surplus compensation per kWh, the hourly consumption for the energy monitoring;
- one device for the account: electricity account balance, Solar Wallet, last bill amount;
- the energy contract template Octopus Energy España electricity.
Read-only: nothing is ever changed on your account; the only request that is not a read is the login. It has never been tested with a real Octopus España account yet: built from the published API and the queries of ha-octopus-spain.
Setup
- Install the integration from the Gladys store, open its configuration.
- Enter the e-mail address and the password you use on the Octopus website, or an API key of your account if Octopus gave you one (used alone when given). Kraken deprecated the e-mail login in 2026: if Octopus removes it, the status says so. The password and the API key are kept by Gladys in its database, never shown again, sent only to Octopus Energy España.
- Account number: only when your login has several accounts (empty: the first one).
- Zone of the supply: peninsula and Balearic Islands (the default), Canary Islands or Ceuta and Melilla. It sets the hours of the periods.
- Save, then Test the connection (at most once a minute).
- In Discovery, add the devices you want.
Devices
Octopus electricity (CUPS …XXXX), the last 4 characters of the CUPS:
| Feature | Unit | Note |
|---|---|---|
| Price per kWh now | EUR/kWh | the price of the current period, taxes included |
| Next price per kWh | EUR/kWh | the next different price within 2 days |
| Price per kWh P1 (punta) | EUR/kWh | taxes included |
| Price per kWh P2 (llano) | EUR/kWh | taxes included |
| Price per kWh P3 (valle) | EUR/kWh | taxes included |
| Surplus compensation per kWh | EUR/kWh | the price of the energy you export |
| Consumption (30 min) | kWh | each hour read split in two equal half hours |
Octopus España account: electricity account balance, Solar Wallet, last bill amount (EUR, as the API gives them). A value the API does not give stays empty, never 0.
The prices are published again at every quarter of an hour from what is held (no request), and no longer once they were read more than 6 hours ago.
The 2.0TD periods
| Days | Peninsula, Balearic and Canary Islands (local time) | Ceuta and Melilla |
|---|---|---|
| Monday to Friday | P1 10-14 and 18-22, P2 8-10, 14-18 and 22-24, P3 0-8 | P1 11-15 and 19-23, P2 8-11, 15-19 and 23-24, P3 0-8 |
| Saturday, Sunday, national holidays of fixed date | P3 all day | P3 all day |
National holidays of fixed date: 1 and 6 January, 1 May, 15 August, 12 October, 1 November, 6, 8 and 25 December (CNMC Circular 3/2020, as of 2026-11). Moving holidays (Good Friday) and regional ones are ordinary days in 2.0TD. A product with the same price in the three periods is priced the same at every hour.
Pace
- The account (supply points, prices, balances, last bill): every hour.
- The consumption of the created supply point: every 6 hours over the last 4 days, and over 14 days once a day after 06:00 and for a new device (the distributor sends the readings a day or more late).
- One request at a time, 2 seconds apart. The time of each read is kept in
/databefore the request: a restart never reads sooner.
The energy contract
Create a contract from the Octopus Energy España electricity template:
- Last 4 characters of the CUPS: empty with a single supply point; required with several (an empty or ambiguous value leaves the contract unpriced, never guessed);
- Fixed charges per month: the power term and the meter rental of your bill, taxes included (the API does not give them).
Every half hour is priced by the integration at the price of its period, taxes included. The API gives the prices in force, never their dates: the integration keeps, at each hourly read, the prices of the next 2 hours (40 days kept). So:
- start the contract on the day after the installation: a half hour before the installation has no price;
- a gap of more than 2 hours without a good read leaves the half hours of the gap without a price: Gladys stopped, Octopus unreachable for about 1 h 30 (the retries after 5, 10, 20 and 40 minutes then fall after the 2 hours kept), a pause after a 429 or a 5xx longer than 2 hours, or a supply point whose prices the API answers in error;
- a price change is seen at the next hourly read;
- changing the zone does not price the past again.
A half hour without a price is never counted 0. Gladys needs a price for every half hour of a request: one missing fails the whole request, and the catch-up of Gladys starts again from the oldest half hour without a cost. A gap therefore delays the costs of the half hours after it, for up to 31 days (the catch-up window of Gladys), until the gap leaves that window. The priced half hours carry no period label.
The template uses the time of Madrid for the days and months of Gladys (billing period, daily totals): in the Canary Islands they start at 23:00 local time. The periods themselves follow the local time of the islands.
Status and errors
| Status | Meaning | What happens |
|---|---|---|
| Octopus refused the login (KT-CT-1138, 1134 or 1135) | the login refused: wrong e-mail, password or API key (1134 and 1135 are documented for refresh tokens; answered to this login, they are taken as a refusal) | no request until you change the credentials or Test succeeds (another account number alone does not lift it) |
| API access is not enabled (KT-CT-11334) | Octopus disabled API access for this user | same |
| Octopus no longer accepts the login by e-mail and password | the schema refuses these fields, or KT-CT-1113 | pause of 1 hour, doubled up to 6 hours; lifted by an API key |
| Octopus blocks the login for now (KT-CT-1136) | a temporary block, seen with valid credentials | pause of 1 hour, doubled up to 6 hours |
| Octopus asked to slow down | HTTP 429 or KT-CT-1199 | pause of Retry-After or 15 minutes, doubled up to 6 hours |
| Octopus is having trouble | HTTP 5xx or KT-CT-7899 | pause of 5 minutes, doubled up to 6 hours |
| Octopus could not be read | network, timeout, unreadable or partial answer, a query refused | tried again after 5, 10, 20, 40 then every 60 minutes |
A 401 or 403 answered to a query (not to the login) is never taken as a
refused password: one new login, then a passing error. The pauses and the
refusal are kept in /data (the refusal as 8 bits of a salted hash of the
credentials, never the credentials).
Other remarks in the status: the prices of a supply point answered in error (the error and the time of the last good read; not kept, not used after 6 hours), prices not given with taxes (not published nor used), several supply points (the consumption is not published), the balances or the consumption not read (the prices go on).
Octopus' new sign-in. If the website accepts your password but the integration says it is refused, your account may use the new sign-in: an API key of the account still works (ask Octopus for one).
What /data holds
/data/octopus-spain.json: the time of the last reads, the pause, the
refusal (8 bits of a salted hash), the supply points seen (at most 8: keyed
hash, last 4 characters, when last seen), the keyed hash of the account and
the prices of the last 40 days. Never the e-mail address, the password, a
token, the id key, the account number nor a whole CUPS.
Limits
- Electricity only, consumption only: the export (surplus) readings are not read in v1.
- The consumption is published only for an account with a single supply point: the readings of the API do not say which supply point they belong to.
- Only the prices taxes included (
variableTermWithTaxes); an indexed product without these three prices has no price in Gladys. - The power term and the contracted power are not read: enter the fixed charges in the contract.
- The times of the status are those of Madrid.
Credits
The GraphQL queries are adapted from ha-octopus-spain (MIT, Miguel Ángel López Vicente). Apache-2.0.
Parámetros de configuración
Estos son los parámetros que Octopus Energy España te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Octopus Energy España account | section | No | Unofficial connector, not affiliated with Octopus Energy. For Octopus Energy customers in Spain. Log in with the e-mail address and password of the Octopus website, or an API key of your account if Octopus gave you one (Kraken deprecated the e-mail login in 2026 and may remove it). The integration reads your electricity supply points (CUPS), the prices of your contract for the three 2.0TD periods (taxes included), the hourly consumption for the Gladys energy monitoring, your balances (electricity account, Solar Wallet) and your last bill. Read-only: nothing is ever changed on your account. Then create an energy contract from the "Octopus Energy España electricity" template. |
| API key (optional) | secret | No | An API key of your Octopus account, if Octopus gave you one: used alone when given. Kept by Gladys in its database, never shown again, sent only to Octopus Energy España. |
| E-mail address | string | No | The e-mail address you log in with on the Octopus website (not needed with an API key). |
| Password | secret | No | Kept by Gladys in its database, never shown again, sent only to Octopus Energy España (api.oees-kraken.energy) to log in. |
| Account number (optional) | string | No | Only needed when your login has several Octopus accounts: empty, the first one is read. |
| Zone of the supply | select | No | Sets the hours of the 2.0TD periods (punta, llano, valle), in the local time of the zone. |
Cómo instalar Octopus Energy España en Gladys
- En Gladys, abre Integraciones: Octopus Energy España aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/lm1lc3n7/gladys-octopus-spain:0.1.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/LM1LC3N7/gladys-octopus-spain.
Octopus Energy España requiere Gladys >=5.3.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
Octopus Energy España es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene LM1LC3N7, no el equipo principal de Gladys.
- Explorar todas las integraciones, nativas y de la comunidad
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación