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 — 10 000 pour une C68_ASYNC). Une requête dépassant sa limite 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.

Détail par point de livraison (summaryPerContract)

Une requête peut porter plusieurs PRM, et réussir pour certains et pas pour d'autres. Chaque requête de la commande détaille donc son résultat point par point dans requests[].summaryPerContract[] : une entrée par PRM, ajoutée au fur et à mesure qu'Enedis répond. Le tableau peut être incomplet tant que la requête est PENDING, et absent tant que rien n'est connu.

La forme des entrées dépend du type de requête, et se reconnaît à _tag, puis à _status.

Courbes de charge (LOADCURVE, R63, R63_SYNC) : LoadcurveRequestContractSummary

La requête porte aussi requestedTimeRange, la période effectivement demandée à Enedis (intervalle ISO 8601 début/fin), à laquelle se rapporte la couverture.

Un point pour lequel Enedis n'a rien renvoyé est final avec timeRangeCoverageRatio: 0, toute la période dans holes et le motif d'Enedis dans errorMessage. Un point couvert en partie a un errorMessage à null : ce sont holes et timeRangeCoverageRatio qui disent ce qui manque.

{
  "type": "R63",
  "status": "SUCCESS",
  "requestedTimeRange": "2026-09-01T00:00:00.000+02:00/2026-10-01T00:00:00.000+02:00",
  "summaryPerContract": [
    {
      "_tag": "LoadcurveRequestContractSummary",
      "_status": "final",
      "prm": "12345678901234",
      "timeRangeCoverageRatio": 0.966667,
      "holes": ["2026-09-12T00:00:00.000+02:00/2026-09-13T00:00:00.000+02:00"],
      "errorMessage": null
    },
    {
      "_tag": "LoadcurveRequestContractSummary",
      "_status": "final",
      "prm": "98765432109876",
      "timeRangeCoverageRatio": 0,
      "holes": ["2026-09-01T00:00:00.000+02:00/2026-10-01T00:00:00.000+02:00"],
      "errorMessage": "La demande ne peut aboutir : …"
    }
  ]
}

Autres requêtes (C68, C68_ASYNC, R64 à R67 et leurs _SYNC) : RawFileContractSummary

Pour C68 et C68_ASYNC, fileUrl est toujours null : les données d'un point sont réparties dans les fichiers de la requête, à lire via dataUrl / dataUrls.

Données effacées (RGPD)

Quand le titulaire d'un point a obtenu l'effacement de ses données (voir Effacement des données), ses données ne sont plus servies, et l'API le dit explicitement. Les autres points d'une requête groupée sont servis comme avant.

GET/integration/enedis/order/{orderId} — dans summaryPerContract, l'entrée du point porte _status: "erased", la date et la raison :

{
  "_tag": "LoadcurveRequestContractSummary",
  "_status": "erased",
  "prm": "12345678901234",
  "erasedAt": "2026-10-14T09:12:00.000Z",
  "reasonFr": "Données effacées le 14/10/2026 suite à une demande d'effacement RGPD : le consentement a été révoqué.",
  "reasonEn": "Data erased on 2026-10-14 following a GDPR erasure request: the consent was revoked."
}

Les entrées RawFileContractSummary ont désormais elles aussi un _status : final, ou erased (avec fileUrl: null). Les fichiers bruts d'une requête groupée sont réécrits sans le point effacé ; pendant cette réécriture — quelques minutes — la requête n'a pas de dataUrl (null, ou dataUrls: []). Si tous les points d'une requête sont effacés, son errorMessage le dit.

GET/integration/enedis/request/{requestId}/data — si tous les points demandés sont effacés (la requête entière, ou ceux de prm), la réponse est une erreur 410 DataErased, qui liste les points dans erasedPrms (prm, erasedAt, reasonFr, reasonEn). Sinon, les points effacés sont absents des données, et listés, séparés par des virgules, dans l'en-tête Switchgrid-Gdpr-Erased-Prms — quel que soit le format (JSON, CSV, XLSX).

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[] (voir Détail par point). 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.