Enedis#

Une fois qu'un Ask est signé, commandez des données Enedis via POST/integration/enedis/order. Une commande (order) contient une liste de requêtes (requests), chacune ciblant un ou plusieurs PRM pour un type de données donné.

Passer une commande#

{
  "requests": [
    {
      "type": "R63",
      "direction": "SOUTIRAGE",
      "prms": ["00046372994792", "00052989142094"]
    },
    {
      "type": "C68_ASYNC",
      "direction": "CONSUMPTION",
      "prms": ["00046372994792", "00052989142094"]
    }
  ]
}

Types de requêtes disponibles#

Le champ type de chaque requête détermine la donnée Enedis récupérée. Les types _SYNC sont synchrones (réponse en quelques secondes, 1 PRM maximum par requête) ; les autres sont asynchrones (la donnée arrive après quelques minutes, jusqu'à 500 PRM par requête). Une requête dépassant 500 PRM est rejetée avec une erreur 400 Bad Request : répartissez les PRM sur plusieurs requêtes.

Toutes les requêtes prennent les prms (obligatoire). Quelques précisions sur les arguments optionnels :

• direction — pour C68_ASYNC et LOADCURVE, les valeurs sont CONSUMPTION (défaut) ou INJECTION. Pour les types R6*, les valeurs sont SOUTIRAGE (défaut) ou INJECTION.

• since / until — par défaut en UTC si aucun fuseau horaire n'est précisé. Plusieurs formes sont acceptées :

  2024-12-10
  2024-12-10T00:00:00
  2024-12-10T12:00:00Z
  2024-12-10T00:00:00+01:00
  2024-12-10T00:00:00[Europe/Paris]
  2024-12-10T00:00:00[CET]
  

  Il est conseillé d'utiliser le format 2024-12-10T00:00:00[Europe/Paris], car Enedis délivre les données de minuit à minuit en heure locale. Les données de la veille s'arrêtent à minuit heure locale.

• enedisRetryAfterLoadcurveActivation — voir Erreurs et stratégie de retry ci-dessous.

Réponse#

L'API répond avec la commande créée. Chaque requête a son propre status, qui évolue au fur et à mesure de la récupération des données.

{
  "id": "47608cf7-1396-47fa-ada0-087de727b291",
  "status": "PENDING_REQUESTS",
  "requests": [
    {
      "type": "R63",
      "status": "PENDING",
      "orderedAt": "2024-11-13T13:46:38.385Z",
      "completedAt": null,
      "errorMessage": null
    },
    {
      "type": "C68_ASYNC",
      "status": "PENDING",
      "orderedAt": "2024-11-13T13:46:38.392Z",
      "completedAt": null,
      "errorMessage": null
    }
  ]
}

Consulter une commande#

Muni d'un orderId, vous pouvez connaître l'avancement de la/des requête(s) de données via GET/integration/enedis/order/{orderId}.

Enedis met généralement 2 à 5 minutes à répondre. Lorsque les données sont prêtes, la réponse renvoie, par requête, un ou plusieurs lien(s) vers les fichiers bruts renvoyés par Enedis dans dataUrl ou dataUrls :

{
  "id": "904ae72d-fd16-446c-914f-fd5ff3eca689",
  "status": "COMPLETED",
  "requests": [
    {
      "type": "C68_ASYNC",
      "status": "SUCCESS",
      "orderedAt": "2024-01-01T10:20:30Z",
      "completedAt": "2024-01-01T10:20:32Z",
      "dataUrl": "https://...",
      "errorMessage": null
    },
    {
      "type": "R63",
      "status": "SUCCESS",
      "orderedAt": "2024-01-01T10:20:30Z",
      "completedAt": "2024-01-01T10:20:32Z",
      "dataUrl": "https://...",
      "errorMessage": null
    }
  ]
}

États d'une commande (order.status)#

Le détail de chaque requête (requests[].status) indique lesquelles ont réussi ou échoué.

États d'une requête (requests[].status)#

NOT_STARTED, QUEUED, PENDING, puis SUCCESS ou FAILED. En cas d'échec, le champ errorMessage décrit l'erreur.

Erreurs et stratégie de retry#

En cas d'échec d'une requête, requests[].status vaut FAILED et errorMessage détaille la cause :

{
  "id": "...",
  "status": "SOME_REQUESTS_FAILED",
  "requests": [
    {
      "type": "R63",
      "status": "FAILED",
      "orderedAt": "2024-07-29T07:52:19.903Z",
      "completedAt": "2024-07-29T07:53:08.629Z",
      "dataUrl": null,
      "errorMessage": "La demande ne peut aboutir : aucun service souscrit de courbe de charge n'est présent pour la période demandée"
    }
  ]
}

Cette section décrit ce que signifient ces erreurs, et quand il est utile — ou inutile — de réessayer.

Où lire l'erreur#

• Sur GET/integration/enedis/order/{orderId}, chaque requête a son status. En cas d'échec, status vaut FAILED et errorMessage porte la cause.

• Quand l'erreur vient d'Enedis, errorMessage commence par le code Enedis entre crochets : [SGT589]: La demande ne peut pas aboutir car le compteur n'est actuellement pas téléopérable.. Le code est donc directement exploitable par votre code :

  const code = request.errorMessage?.match(/^\[([A-Z0-9]+)\]/)?.[1] ?? null;
  

• Pour les requêtes asynchrones multi-PRM, une requête peut réussir pour certains PRM et échouer pour d'autres. Le détail par PRM se trouve dans requests[].summaryPerContract[] (prm, errorMessage, fileUrl). Dans ce cas, le motif renvoyé par Enedis est un texte libre, sans code SGT… (voir Erreurs sans code).

• Le webhook order.request_failed vous notifie de chaque requête en échec ; il ne contient que les identifiants, l'errorMessage se lit sur la commande.

Les cinq classes d'erreurs#

Catalogue des codes Enedis#

Les codes ci-dessous sont ceux que nous voyons réellement passer sur les requêtes de données. Le libellé est celui d'Enedis (il peut varier à la marge).

Erreurs sans code (requêtes asynchrones)#

Pour les requêtes asynchrones (R63, R64, R65, R66, R67, C68_ASYNC), Enedis renvoie d'abord un compte-rendu par PRM. Les PRM refusés portent un motif en texte libre, restitué tel quel dans requests[].summaryPerContract[].errorMessage. Le plus fréquent :

La demande ne peut aboutir : aucun service souscrit de courbe de charge n'est présent pour la période demandée

Courbe de charge non disponible. Ce motif signifie en général que la courbe de charge n'a jamais été collectée pour ce compteur : sur un compteur Linky, Enedis ne publie la courbe que pour les périodes où la collecte (service CCDC) était souscrite.

Quand un de ces motifs tombe sur une demande de courbe de charge, Switchgrid interroge Enedis pour savoir si la collecte est souscrite sur le point :

• elle l'est → le motif veut bien dire ce qu'il dit, il n'y a pas de mesure sur la période. Le motif d'Enedis vous est restitué tel quel ;

• elle ne l'est pas → nous demandons immédiatement l'activation de la collecte quotidienne à Enedis, et l'échec vous est restitué avec un message explicite plutôt qu'avec le motif générique :

  La collecte de courbe de charge n'était pas souscrite sur ce point : aucune donnée n'a donc été enregistrée pour la période demandée. L'activation de la collecte vient d'être demandée à Enedis ; relancez une demande identique dans quelques heures.

  Le reasonCode associé est ENEDIS_CCDC_AUCUN_SERVICE_SOUSCRIT — le même qu'avant juin 2026, la signification n'ayant pas changé.

Recréez une commande identique quelques heures plus tard ou le lendemain ; vous pourrez alors récolter jusqu'à 3-4 mois de données historiques stockées dans le compteur Linky.

{
  "requests": [
    {
      "type": "R63",
      "direction": "SOUTIRAGE",
      "prms": ["00045855908792"],
      "enedisRetryAfterLoadcurveActivation": true
    }
  ]
}

Erreurs renvoyées par Switchgrid#

Certaines demandes sont refusées avant tout appel à Enedis. Elles se reconnaissent à l'absence de code SGT… :

Stratégie de retry recommandée#

1. Lire le code avant de décider. Aucun retry n'est justifié sans avoir regardé le code d'erreur : les classes A, B et C ne deviendront jamais des succès en réessayant.
2. Plafonner le nombre de tentatives à 3, tous cas confondus, et espacer : 15 min, 1 h, puis le lendemain. Une boucle de 10 ou 20 tentatives ne récupère aucune donnée supplémentaire.
3. Ne pas piloter les retries depuis le front. Un utilisateur qui rafraîchit sa page ne doit pas déclencher une nouvelle commande. Faites porter la décision par un job côté serveur, avec l'état de la commande en base.
4. Écouter les webhooks plutôt que de repasser une commande. Une commande PENDING finit toujours par se terminer (succès ou échec) ; la re-commander en parallèle double la charge sans accélérer quoi que ce soit.
5. Mémoriser les échecs définitifs par PDL. Un SGT4M1 ou un SGT401 devrait sortir le PDL de votre boucle de rafraîchissement, définitivement.

Anticiper les échecs#

Deux des erreurs les plus fréquentes sont visibles avant de commander des données de consommation, dans la réponse d'une requête C68_ASYNC (données techniques et contractuelles) :

Ce que Switchgrid fait déjà de son côté#

• Retry automatique des erreurs techniques : un SGT500 (ou une erreur réseau) est rejoué jusqu'à 3 fois avant de vous être remonté.
• Aucun retry automatique sur les erreurs fonctionnelles : elles vous sont remontées telles quelles, immédiatement.
• Réutilisation des données déjà récoltées : les requêtes R64_SYNC / R65_SYNC peuvent être servies depuis nos propres données quand elles couvrent la période demandée, sans appel à Enedis. Cette réutilisation ne s'applique pas aux requêtes asynchrones, qui sont toujours transmises à Enedis.
• Garde-fou anti-doublon : sur demande, nous pouvons activer sur votre projet le rejet des requêtes strictement identiques à une requête déjà en cours (fenêtre de 2 h).
• Activation de la courbe de charge puis rejeu de la demande, quand la collecte n'était pas encore souscrite.
• Suivi des points en défaut : nous suivons les SGT589, SGT476 et SGT583 récurrents. Pour les défauts de communication (SGT589), Enedis considère le problème déjà connu de ses services et n'accepte un signalement qu'au-delà de 6 mois d'interruption continue.

Récupérer les données de courbe de charge à pas constant#

Pour les courbes de charge (R63, R63_SYNC, LOADCURVE), GET/integration/enedis/request/{requestId}/data restitue les données mises à un pas de temps constant, au format json (défaut), csv ou xlsx. Le requestId correspond à l'id de la requête dans la commande.

Le paramètre period contrôle le pas de temps (défaut 1h). Les paramètres since / until permettent de borner la période, et prm de filtrer sur certains PRM.

Format CSV#

Les données sont en heure UTC, en « pas commençant » (la valeur correspond à l'intervalle qui démarre à startDate).

startDate,powerInWatts
2024-12-15T23:00:00.000Z,321
2024-12-15T23:10:00.000Z,294

Format JSON#

{
  "period": "PT600S",
  "startsAt": "2024-12-15T23:00:00.000Z",
  "endsAt": "2024-12-16T23:00:00.000Z",
  "values": [321, 294]
}

Format brut Enedis#

Pour les requêtes de type R6*, les données restent disponibles aux formats retournés par Enedis : téléchargez le(s) fichier(s) référencé(s) par dataUrl / dataUrls dans la réponse de la commande.

Prms de test pour Enedis#

Les PRM de test d'Enedis, la façon de provoquer un contrat NOT_VALID avec le header switchgrid-test-env: true, puis de rejouer le dépôt de justificatif, sont décrits dans le guide de consentement : Tester la création d'un Ask.