@flecoufle/node-red-linky 2.0.0

Récupérer de Linky les données de consommation et production d'énergie via l'API Enedis

npm install @flecoufle/node-red-linky

node-red-linky

Package Node-RED Linky pour récupérer les données de consommation et production d'énergie via l'API Enedis Mesure synchrone V2 (exposée par Conso API).

Installation

Via la palette l'éditeur: @flecoufle/node-red-linky

ou via npm:

npm install @flecoufle/node-red-linky

Prérequis

• Node.js: >= 22.0.0 (exigé par got 16)
• Node-RED: >= 4.0.0
• Dépendances:
  • got 16.2.0

Mise en oeuvre

• Obtenir un accès API (le token) à votre compteur: API Conso vous redirigera vers https://conso.boris.sh
• Exemples d'utilisation du noeud node-red-linky une fois le noeud installé
• Documentation Conso API (type, paramètres et format de réponse)
• Migration 2026 (ancienne API Metering data V5 → Mesure synchrone V2)
• Documentation de Enedis API Data-Connect (pour information uniquement)

⚠️ Important - Mise en cache des appels

À partir de la version 1.4.0, le node limite les appels pour respecter les quotas de l'API et éviter le bannissement de votre IP, une mise en cache est mise en place pour permettre la continuité de service. Cette fonction est appliquée par requête unique (l'API sous-jacente elle-même renvoie déjà des données qui ne changent pas, donc cette fonction ne modifie en rien les informations retournées).

Pour les utilisateurs des versions antérieures: veuillez mettre à jour pour bénéficier de cette protection.

Configuration et Paramètres

Paramètres obligatoires (peuvent être passés via le payload)

Paramètres optionnels (uniquement via le payload)

Priorité du token et du PRM

Les valeurs sont recherchées dans cet ordre, la première valeur non vide gagnant :

1. payload.token / payload.pointId (ou payload.prm)
2. Credentials Node-RED du noeud
3. Noeud de configuration linky-api-config
4. Champs Token / PRM saisis directement dans le noeud

Validation locale

Avant chaque appel, le noeud vérifie :

• le PRM contient exactement 14 chiffres ;
• les dates utilisent le format YYYY-MM-DD et dateDebut est strictement antérieure à dateFin ;
• les courbes de charge (courbe_de_charge_*) couvrent au maximum 7 jours ;
• les options mesuresPas et grandeurPhysique pour la puissance max.

Une requête invalide est rejetée sans consommer le quota API.

Types d'API disponibles

Les types ci-dessous correspondent à l'API Mesure synchrone V2. La date de fin (dateFin) est exclue.

Consommation

• consommation_quotidienne - Consommation énergétique quotidienne (Wh)

  • Historique : jusqu'à 36 mois et 15 jours avant la date d'appel
  • Chaque valeur est datée

• courbe_de_charge_consommation - Courbe de charge en soutirage

  • Profondeur : une semaine maximum par appel
  • Valeurs : puissances moyennes de consommation en W (intervalle par défaut 30 mn)
  • Historique : jusqu'à 24 mois et 15 jours avant la date d'appel
  • Journées complètes de minuit à minuit (heures locales)

• puissance_conso_max_quotidienne - Puissance maximale soutirée quotidienne (VA)

  • Options : mesuresPas (P1D/P1M) et grandeurPhysique (PMA/TOUT)
  • Historique : jusqu'à 36 mois et 15 jours avant la date d'appel
  • Chaque valeur est datée

• index_consommation - Index de consommation (compteur)

  • Réponse structurée par contexte, calendrier et cadranTotalisateur

Production

• production_quotidienne - Production énergétique quotidienne (Wh)

  • Historique : jusqu'à 36 mois et 15 jours avant la date d'appel
  • Chaque valeur est datée

• courbe_de_charge_production - Courbe de charge de production

  • Profondeur : une semaine maximum par appel
  • Valeurs : puissances moyennes de production en W (intervalle par défaut 30 mn)
  • Historique : jusqu'à 24 mois et 15 jours avant la date d'appel
  • Journées complètes de minuit à minuit (heures locales)

• index_production - Index de production (compteur)

  • Réponse structurée par contexte, calendrier et cadranTotalisateur

Compatibilité avec les anciens types

Les anciens types Metering data V5 restent acceptés comme alias et sont traduits automatiquement :

Les anciens noms de paramètres prm, start et end sont également acceptés en repli de pointId, dateDebut et dateFin.

Format de réponse (V2)

Le noeud retourne le JSON brut de l'API Mesure synchrone V2, sans normalisation. Exemple pour consommation_quotidienne :

{
  "idPrm": "12345678901234",
  "periode": { "dateDebut": "2026-09-01", "dateFin": "2026-10-01" },
  "pas": "P1D",
  "grandeur": [
    {
      "grandeurMetier": "CONS",
      "grandeurPhysique": "EA",
      "unite": "Wh",
      "points": [
        { "v": "6261", "d": "2026-09-01" },
        { "v": "4882", "d": "2026-09-02" }
      ],
      "calendrier": []
    }
  ],
  "contexte": []
}

⚠️ Changement de format : depuis la version 1.5.0, les données ne sont plus dans payload.interval_reading. Utilisez payload.grandeur[].points[] dans les noeuds en aval (par exemple payload.grandeur[0].points). Les types index_* exposent leurs séries dans payload.contexte[].grandeur[].

Migration 2026

L'ancienne API Enedis Metering data V5 a été arrêtée en octobre 2026. Depuis la version 1.5.0, node-red-linky utilise l'API Mesure synchrone V2 :

1. Remplacez le type de vos payloads par son équivalent V2 (voir le tableau ci-dessus).
2. Renommez si possible prm → pointId, start → dateDebut, end → dateFin.
3. Adaptez les noeuds en aval au nouveau format de réponse (grandeur[].points[]).
4. Pour puissance_conso_max_quotidienne, ajustez au besoin mesuresPas et grandeurPhysique.

Voir https://conso.boris.sh/migration-2026.

Migration vers la version 2.0.0 (got 16.2.0)

La version 2.0.0 migre de got 13.0.0 vers got 16.2.0. Cette mise à jour est majeure :

• Node.js >= 22.0.0 est requis : got 16 déclare engines.node >= 22. Mettez à jour Node-RED et son runtime Node.js avant d'installer cette version.
• Node-RED >= 4.0.0 est requis : les exemples utilisent le nœud global-config introduit dans Node-RED 4.0. Les versions 3.x et antérieures ne sont plus supportées.
• got 16 est ESM uniquement : require('got') n'est plus possible. Le noeud charge la dépendance via await import('got') et utilise son export par défaut.
• L'export nommé got a été supprimé. Si vous réutilisez le code du noeud, remplacez const { got } = await import('got') par const { default: got } = await import('got').
• Les options utilisées par le noeud restent compatibles : timeout.*, retry.limit, retry.errorCodes, responseType et throwHttpErrors. Le corps de la réponse reste disponible dans response.body et error.response.body.

Aucune modification des flows n'est nécessaire. Les versions Node.js antérieures à 22 ne peuvent plus charger le module.

Limitation quotidienne des appels et système de cache

Un système de limitation quotidienne est mis en place pour éviter les appels API excessifs pour une même requête identique. Les réponses sont mises en cache, permettant de servir les données en cache quand la limite est atteinte. Cette fonctionnalité permet d'éviter le blocage d'IP, voir "Conseils d'utilisation" sur Conso API

Fonctionnement de la limitation

• Limite par défaut: 3 appels par jour pour une requête identique

• Configuration: La limite peut être ajustée via le paramètre options_api_daily_limit (en cas de besoin spécifique peut être modifiée, attention au risque de bannissement)

• Signature de requête: Chaque requête est identifiée par une signature unique (hash SHA256) et mise en cache (cache de votre instance Node-RED dans une variable de contexte du noeud, donc reste chez vous) basée sur:

  • Le type d'API canonique (type, alias legacy traduits)
  • Le point de livraison (pointId)
  • Les dates de début et fin (dateDebut, dateFin)
  • Les options de puissance max (mesuresPas, grandeurPhysique) le cas échéant
  • L'endpoint API (endpoint)
  • Les configurations de timeout
  • La limite de retry

  Le jour de l'appel, le token, options_api_daily_limit, random_delay et debug ne font pas partie de la signature : le cache et les compteurs étant réinitialisés chaque jour, ils ne changent pas les données retournées par l'API.

• Réinitialisation automatique: Le compteur se réinitialise automatiquement chaque jour à minuit UTC

Le cache et les compteurs sont stockés dans le contexte du noeud, en mémoire avec le context store memory par défaut de Node-RED. Ils sont donc perdus au redémarrage de Node-RED, et le quota est recalculé à partir de zéro.

Comportement avec cache

• Appel réussi: La réponse est automatiquement mise en cache avec la signature de la requête
• Limite atteinte:
  • Une réponse en cache est retournée (statut du noeud: jaune)
  • Si aucune réponse n'a pu être mise en cache (statut du noeud: rouge) cas de l'API en erreurs successives "Daily limit of X calls for this request reached. No cache available." sera affiché dans le log

Dépannage

Le noeud remonte les erreurs HTTP sous la forme statusCode <code>: <corps de la réponse>.

Vérifiez aussi les logs Node-RED : les options debug du payload affichent l'URL appelée et les options de requête (token masqué).

Développement (Docker Compose)

Le stack de développement ne nécessite que Docker et Docker Compose sur l'hôte.

make help        # liste des commandes
make doctor      # vérifie Docker, Compose et le port
make up          # installe les dépendances puis démarre Node-RED sur http://localhost:1880
make watch       # redémarre Node-RED à chaque modification de linky/
make down        # arrête le stack (les flows Node-RED sont conservés)

Le module est monté dans /data/node_modules/@flecoufle/node-red-linky : Node-RED le charge comme une installation via la palette. Les dépendances npm (got) sont installées dans un conteneur Node 22, sans nécessiter Node.js sur l'hôte.

Autres commandes utiles :

Les valeurs par défaut (port, fuseau horaire, versions des images) sont dans le Makefile et peuvent être surchargées dans un fichier .env (voir .env.example, make env).