Intégration domotique Octopus Energy España, gratuite et open source
Non officiel : prix Octopus Energy Espagne par période 2.0TD, conso horaire, soldes, facture.
Publiée par LM1LC3N7
- Appareils
- Version 0.1.1
- Nécessite Gladys >=5.3.0
- ★ 0
Intégration non officielle, sans lien avec Octopus Energy, pour les clients
d'Octopus Energy España. Elle lit votre compte par l'API GraphQL Kraken
officielle d'Octopus España (api.oees-kraken.energy) et donne à Gladys :
- un appareil par point de fourniture d'électricité (CUPS) : le prix du kWh actuel et le suivant, les prix des trois périodes 2.0TD (taxes comprises), la compensation des excédents par kWh, la consommation horaire pour le suivi énergétique ;
- un appareil pour le compte : solde du compte électricité, Solar Wallet, montant de la dernière facture ;
- le modèle de contrat d'énergie Octopus Energy España électricité.
Lecture seule : rien n'est jamais modifié sur votre compte ; la seule requête qui n'est pas une lecture est la connexion. Elle n'a jamais été testée avec un vrai compte Octopus España pour l'instant : construite d'après l'API publiée et les requêtes de ha-octopus-spain.
Mise en route
- Installez l'intégration depuis le store de Gladys, ouvrez sa configuration.
- Saisissez l'adresse e-mail et le mot de passe du site d'Octopus, ou une clé d'API de votre compte si Octopus vous en a donné une (utilisée seule si elle est saisie). Kraken a déprécié la connexion par e-mail en 2026 : si Octopus la retire, le statut le dit. Le mot de passe et la clé d'API sont gardés par Gladys dans sa base, jamais réaffichés, envoyés seulement à Octopus Energy España.
- Numéro de compte : seulement si votre connexion a plusieurs comptes (vide : le premier).
- Zone de la fourniture : péninsule et Baléares (par défaut), Canaries ou Ceuta et Melilla. Elle fixe les heures des périodes.
- Enregistrez, puis Tester la connexion (au plus une fois par minute).
- Dans la Découverte, ajoutez les appareils voulus.
Appareils
Octopus électricité (CUPS …XXXX), les 4 derniers caractères du CUPS :
| Fonctionnalité | Unité | Remarque |
|---|---|---|
| Prix du kWh actuel | EUR/kWh | le prix de la période en cours, taxes comprises |
| Prochain prix du kWh | EUR/kWh | le prochain prix différent dans les 2 jours |
| Prix du kWh P1 (punta) | EUR/kWh | taxes comprises |
| Prix du kWh P2 (llano) | EUR/kWh | taxes comprises |
| Prix du kWh P3 (valle) | EUR/kWh | taxes comprises |
| Compensation des excédents par kWh | EUR/kWh | le prix de l'énergie que vous injectez |
| Consommation (30 min) | kWh | chaque heure lue partagée en deux demi-heures égales |
Compte Octopus España : solde du compte électricité, Solar Wallet, montant de la dernière facture (EUR, tels que l'API les donne). Une valeur que l'API ne donne pas reste vide, jamais 0.
Les prix sont republiés à chaque quart d'heure depuis ce qui est connu (sans requête), et plus du tout s'ils ont été lus il y a plus de 6 heures.
Les périodes 2.0TD
| Jours | Péninsule, Baléares et Canaries (heure locale) | Ceuta et Melilla |
|---|---|---|
| Du lundi au vendredi | P1 10-14 et 18-22, P2 8-10, 14-18 et 22-24, P3 0-8 | P1 11-15 et 19-23, P2 8-11, 15-19 et 23-24, P3 0-8 |
| Samedi, dimanche, fêtes nationales à date fixe | P3 toute la journée | P3 toute la journée |
Fêtes nationales à date fixe : 1er et 6 janvier, 1er mai, 15 août, 12 octobre, 1er novembre, 6, 8 et 25 décembre (circulaire CNMC 3/2020, état de 2026-11). Les fêtes mobiles (Vendredi saint) et régionales sont des jours ordinaires en 2.0TD. Un produit au même prix dans les trois périodes coûte le même prix à toute heure.
Rythme
- Le compte (points de fourniture, prix, soldes, dernière facture) : toutes les heures.
- La consommation du point de fourniture créé : toutes les 6 heures sur les 4 derniers jours, et sur 14 jours une fois par jour après 6 h et pour un nouvel appareil (le distributeur envoie les relevés avec un jour de retard ou plus).
- Une requête à la fois, à 2 secondes d'écart. L'heure de chaque lecture est
gardée dans
/dataavant la requête : un redémarrage ne lit jamais plus tôt.
Le contrat d'énergie
Créez un contrat depuis le modèle Octopus Energy España électricité :
- 4 derniers caractères du CUPS : vide avec un seul point de fourniture ; obligatoires avec plusieurs (une valeur vide ou ambiguë laisse le contrat sans prix, jamais deviné) ;
- Frais fixes par mois : le terme de puissance et la location du compteur de votre facture, taxes comprises (l'API ne les donne pas).
Chaque demi-heure est tarifée par l'intégration au prix de sa période, taxes comprises. L'API donne les prix en vigueur, jamais leurs dates : à chaque lecture horaire, l'intégration garde les prix des 2 heures suivantes (gardés 40 jours). Donc :
- faites commencer le contrat le lendemain de l'installation : une demi-heure d'avant l'installation n'a pas de prix ;
- plus de 2 heures sans bonne lecture laissent les demi-heures du trou sans prix : Gladys arrêté, Octopus injoignable environ 1 h 30 (les reprises à 5, 10, 20 et 40 minutes tombent alors après les 2 heures gardées), une pause après un 429 ou un 5xx de plus de 2 heures, ou un point de fourniture dont l'API renvoie les prix en erreur ;
- un changement de prix est vu à la lecture horaire suivante ;
- changer de zone ne retarife pas le passé.
Une demi-heure sans prix n'est jamais comptée 0. Gladys exige un prix pour chaque demi-heure d'une requête : un seul manquant fait échouer toute la requête, et le rattrapage de Gladys reprend depuis la plus ancienne demi-heure sans coût. Un trou retarde donc les coûts des demi-heures suivantes, jusqu'à 31 jours (la fenêtre de rattrapage de Gladys), le temps que le trou sorte de cette fenêtre. Les demi-heures tarifées ne portent pas d'étiquette de période.
Le modèle utilise l'heure de Madrid pour les jours et les mois de Gladys (période de facturation, totaux du jour) : aux Canaries, ils commencent à 23 h locale. Les périodes, elles, suivent l'heure locale des îles.
Statut et erreurs
| Statut | Sens | Ce qui se passe |
|---|---|---|
| Octopus a refusé la connexion (KT-CT-1138, 1134 ou 1135) | connexion refusée : e-mail, mot de passe ou clé d'API faux (1134 et 1135 sont documentés pour les jetons de rafraîchissement ; répondus à cette connexion, ils sont pris pour un refus) | aucune requête tant que vous ne changez pas les identifiants ou que Tester ne réussit pas (un autre numéro de compte seul ne le lève pas) |
| L'accès à l'API n'est pas activé (KT-CT-11334) | Octopus a désactivé l'accès à l'API pour cet utilisateur | idem |
| Octopus n'accepte plus la connexion par e-mail et mot de passe | le schéma refuse ces champs, ou KT-CT-1113 | pause d'1 heure, doublée jusqu'à 6 heures ; levée par une clé d'API |
| Octopus bloque la connexion pour le moment (KT-CT-1136) | blocage passager, vu avec des identifiants valides | pause d'1 heure, doublée jusqu'à 6 heures |
| Octopus a demandé de ralentir | HTTP 429 ou KT-CT-1199 | pause de Retry-After ou 15 minutes, doublée jusqu'à 6 heures |
| Octopus a un problème | HTTP 5xx ou KT-CT-7899 | pause de 5 minutes, doublée jusqu'à 6 heures |
| Octopus n'a pas pu être lu | réseau, délai, réponse illisible ou partielle, requête refusée | nouvel essai après 5, 10, 20, 40 puis toutes les 60 minutes |
Un 401 ou 403 répondu à une requête (pas à la connexion) n'est jamais pris
pour un mot de passe refusé : une nouvelle connexion, puis une erreur
passagère. Les pauses et le refus sont gardés dans /data (le refus comme
8 bits d'une empreinte salée des identifiants, jamais les identifiants).
La nouvelle connexion d'Octopus. Si le site accepte votre mot de passe mais que l'intégration le dit refusé, votre compte utilise peut-être la nouvelle connexion : une clé d'API du compte fonctionne encore (demandez-en une à Octopus).
Autres remarques du statut : prix d'un point de fourniture renvoyés en erreur (l'erreur et l'heure de la dernière bonne lecture ; ni gardés, ni utilisés après 6 heures), prix non donnés taxes comprises (ni publiés ni utilisés), plusieurs points de fourniture (la consommation n'est pas publiée), soldes ou consommation non lus (les prix continuent).
Ce que contient /data
/data/octopus-spain.json : l'heure des dernières lectures, la pause, le
refus (8 bits d'une empreinte salée), les points de fourniture vus (8 au plus :
empreinte à clé, 4 derniers caractères, dernière fois vu), l'empreinte à clé
du compte et les prix des 40 derniers jours. Jamais l'adresse e-mail, le mot
de passe, un jeton, la clé des identifiants, le numéro de compte ni un CUPS
entier.
Limites
- Électricité seulement, consommation seulement : les relevés d'injection (excédents) ne sont pas lus en v1.
- La consommation n'est publiée que pour un compte à un seul point de fourniture : les relevés de l'API ne disent pas à quel point ils appartiennent.
- Seulement les prix taxes comprises (
variableTermWithTaxes) ; un produit indexé sans ces trois prix n'a pas de prix dans Gladys. - Le terme de puissance et la puissance souscrite ne sont pas lus : saisissez les frais fixes dans le contrat.
- Les heures du statut sont celles de Madrid.
Crédits
Les requêtes GraphQL sont adaptées de ha-octopus-spain (MIT, Miguel Ángel López Vicente). Apache-2.0.
Paramètres de configuration
Voici les paramètres demandés par Octopus Energy España dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Compte Octopus Energy España | section | Non | Connecteur non officiel, sans lien avec Octopus Energy. Pour les clients d'Octopus Energy en Espagne. Connectez-vous avec l'adresse e-mail et le mot de passe du site d'Octopus, ou une clé d'API de votre compte si Octopus vous en a donné une (Kraken a déprécié la connexion par e-mail en 2026 et peut la retirer). L'intégration lit vos points de fourniture d'électricité (CUPS), les prix de votre contrat pour les trois périodes 2.0TD (taxes comprises), la consommation horaire pour le suivi énergétique de Gladys, vos soldes (compte électricité, Solar Wallet) et votre dernière facture. Lecture seule : rien n'est jamais modifié sur votre compte. Créez ensuite un contrat d'énergie depuis le modèle « Octopus Energy España électricité ». |
| Clé d'API (facultative) | secret | Non | Une clé d'API de votre compte Octopus, si Octopus vous en a donné une : utilisée seule si elle est saisie. Gardée par Gladys dans sa base, jamais réaffichée, envoyée seulement à Octopus Energy España. |
| Adresse e-mail | string | Non | L'adresse e-mail avec laquelle vous vous connectez sur le site d'Octopus (inutile avec une clé d'API). |
| Mot de passe | secret | Non | Gardé par Gladys dans sa base, jamais réaffiché, envoyé seulement à Octopus Energy España (api.oees-kraken.energy) pour se connecter. |
| Numéro de compte (facultatif) | string | Non | Utile seulement si votre connexion a plusieurs comptes Octopus : vide, le premier est lu. |
| Zone de la fourniture | select | Non | Fixe les heures des périodes 2.0TD (punta, llano, valle), à l'heure locale de la zone. |
Comment installer Octopus Energy España dans Gladys
- Dans Gladys, ouvrez Intégrations : Octopus Energy España apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
- Cliquez sur Installer. Gladys télécharge l'image Docker (
ghcr.io/lm1lc3n7/gladys-octopus-spain:0.1.1), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration). - Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
- Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/LM1LC3N7/gladys-octopus-spain.
Octopus Energy España nécessite Gladys >=5.3.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.
Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.
À propos des intégrations externes
Octopus Energy España est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par LM1LC3N7, et non par l'équipe cœur de Gladys.
- Parcourir toutes les intégrations, natives et communautaires
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation