Introduction#

Ceci est un guide d'utilisation de notre API disponible sur api.switchgrid.tech. Une spécification OpenAPI est également disponible.

Cette API expose les intégrations aux gestionnaires de réseau (Enedis, GRDF, Strasbourg Électricité Réseaux) sous le préfixe /integration. Les principaux endpoints Enedis sont :

• POST/integration/enedis/search_contract - rechercher un contrat d'électricité Enedis
• POST/integration/enedis/order - passer une commande de données Enedis
• GET/integration/enedis/order/{orderId} - consulter une commande et récupérer ses données
• GET/integration/enedis/request/{requestId}/data - récupérer les données d'une courbe de charge à pas constant

L'ancienne API Enedis reste accessible sur app.switchgrid.tech/enedis/v2 (voir le Guide API v2). Les demandes de consentement (asks) créées avec v0 peuvent être utilisées indifféremment avec les commandes des deux versions.

Authentification#

Tous les appels sont effectués avec un header d'authentification Authorization: Bearer <Token>. Les tokens peuvent être créés et renouvelés via l'interface https://app.switchgrid.tech.

Toutes les requêtes doivent inclure le header x-api-version: v0 pour cibler cette version de l'API.

curl https://api.switchgrid.tech/ask \
  -H "Authorization: Bearer <Token>" \
  -H "x-api-version: v0"

Collecter le consentement utilisateur#

Créez votre premier Ask avec POST/ask#

Voici un exemple du corps de la requête POST/ask pour un Ask avec un contrat gas et un contrat electricity provenant de GET/integration/enedis/search_contract.

Vous pouvez voir les détails de cet endpoint dans la documentation de l'endpoint POST/ask.

contracts#

Vous indiquez ici les contrats pour lesquels vous souhaitez obtenir le consentement de l'utilisateur. Il y a 3 formes possibles

• un UUID obtenu via POST/integration/enedis/search_contract. Cet endpoint permet de confirmer l'existence d'un contrat dans la base Enedis. Vous obtenez alors un UUID, que vous pouvez directement réutiliser ici

• une description du contrat d'électricite (_energyType: electricity) avec le numéro de PDL et les informations du titulaire :

  {
    "_energyType": "electricity",
    "deliveryPointId": "00059461297239",
    "holder": {
      "_tag": "NaturalPerson",
      "fullName": "Jean Dupont"
    },
    "address": {
      "rueEtNumero": "17 avenue Charles de Gaulle",
      "codePostal": "75007",
      "commune": "Paris"
    }
  }
  

  Le deliveryPointId est ici le numéro de PDL (PRM), 14 chiffres.

• une description du contrat de gaz (_energyType: gas) avec le numéro de PCE et les informations du titulaire :

  {
    "_energyType": "gas",
    "deliveryPointId": "01059461297239",
    "holder": {
      "_tag": "NaturalPerson",
      "fullName": "Jean Dupont"
    },
    "address": {
      "rueEtNumero": "17 avenue Charles de Gaulle",
      "codePostal": "75007",
      "commune": "Paris"
    }
  }
  

  Le deliveryPointId est ici le numéro de PCE (14 chiffres, ou GI suivi de 6 chiffres).

Limites en nombre de contrats dans un Ask

Aujourd'hui, on limite selon le type de contrat :

Dépôt de justificatif de contrat#

Lorsque POST/integration/enedis/search_contract ne trouve pas de contrat (par ex. en raison d'une différence de nom dans la base du fournisseur, noms en 2 lettres, etc.), vous pouvez toujours créer un Ask avec une ou plusieurs entrées dans contracts de type electricity ou gas (le statut de l'Ask sera NOT_VALID) puis téléverser un justificatif — typiquement une facture d'électricité - pour prouver le lien entre la personne titulaire et le point de livraison concerné. Lorsque le justificatif est validé, le contrat est validé et l'Ask passe en statut PENDING_USER_ACTION, prêt à être signé par l'utilisateur.

Processus#

{
  "contracts": [
    {
      "_energyType": "electricity",
      "deliveryPointId": "09284757283947",
      "holder": {
        "_tag": "NaturalPerson",
        "fullName": "Jean Dupont"
      },
      "address": {
        "rueEtNumero": "17 avenue Charles de Gaulle",
        "codePostal": "75007",
        "commune": "Paris"
      }
    }
  ],
  "consentDuration": "1 year"
}

Révoquer un Ask#

Si vous souhaitez révoquer un Ask, vous pouvez utiliser l'endpoint POST/ask/{askId}/revoke. Pour l'instant, il n'est pas possible de révoquer partiellement un Ask (seulement certains contrats).

Récupérer les données#

Une fois qu'un Ask est signé, vous pouvez commander des données depuis les endpoints de cette version de l'API, regroupés sous le chemin /integration, pour Enedis, GRDF et Strasbourg Électricité Réseaux. Voir les détails ci-dessous.

Les anciens endpoints de l'API enedis-v2 restent disponibles et acceptent eux aussi les asks créés en v0.

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 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#

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"
    }
  ]
}

Courbe de charge non disponible — l'erreur « La demande ne peut aboutir : aucun service souscrit de courbe de charge n'est présent pour la période demandée » signifie en général que la courbe de charge n'a jamais été collectée pour ce compteur. Switchgrid fait alors automatiquement et immédiatement la demande d'activation de la collecte quotidienne auprès d'Enedis. 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
    }
  ]
}

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#

En mettant le header HTTP switchgrid-test-env à true lors de la création de l'Ask, vous pouvez utiliser les Prms suivants pour tester différents scénarios de contrats et de données. Si le code postal est différent dans l'Ask, la vérification d'adresse échouera.

Pour tester le téléversement de preuve :

• créez un Ask avec
  • le PRM 00056092042209
  • un code postal différent de celui du PRM, comme 75001
  • le header switchgrid-test-env: true
• l'ask retourné doit être en statut NOT_VALID avec un contrat en statut NOT_FOUND
• utilisez l'endpoint POST/ask/{askId}/ownership_proof pour téléverser une facture d'électricité valide pour ce Prm.
• utilisez ensuite l'enpoint de test POST/ask/ownership_proof/{proofId} pour valider la preuve téléversée, avec le body {"acceptOrReject": "accept"} pour accepter la preuve, ou {"acceptOrReject": "reject"} pour la rejeter.
  ⚠️

  Cet enpoint est uniquement utilisable avec les Asks créés avec le header switchgrid-test-env: true. Il ne peut pas être utilisé pour accepter des preuves pour des Asks réels. Dans le parcours réel, les preuves téléversées sont vérifiées par Switchgrid.

GRDF#

Pour commander les index journaliers de GRDF, utilisez ce qui suit.

{
  "pce": "00000000000001"
}

Corps de POST/integration/grdf-adict/donnees-informatives

Strasbourg Électricité Réseaux (ESR)#

Endpoints#

POST/integration/esr/contract#

Objectif : Métadonnées détaillées du contrat associé au point de livraison ESR, incluant le statut du contrat et les identifiants contractuels.

{
  "rtpl": "..."
}

{
    "rtpl": "...",
    "usagePoint": {
        "usagePointId": "...",
        "usagePointStatus": "COM",
        "meterType": "compteur communicant bleu"
    },
    "contract": {
        "segment": "C5",
        "subscribedPower": "6 kVA",
        "lastActivationDate": "2024-09-12",
        "distributionTariff": "CU ADT 4 postes",
        "contractType": "Contrat unique",
        "contratStatus": "Actif",
        "lastDistributionTariffChangeDate": "2024-09-12",
        "offpeakHours": "23:00-07:00"
    }
}

POST/integration/esr/maximum-powers#

Objectif : Récupère les valeurs de puissance maximale enregistrées pour le RTPL sur des périodes définies.

{
    "rtpl": "...",
    "since": "2023-02-23",
    "until": "2023-02-24"
}

{
    "rtpl": "...",
    "since": "2026-02-23",
    "until": "2026-02-24",
    "count": 1096,
    "data": [
        {
            "value": 2915,
            "pas": null,
            "libelle": null,
            "timestamp": "2026-02-23T08:25:00.000+00:00",
            "timestampStorage": "2026-02-23T08:25:33.409+00:00"
        }
    ]
}

POST/integration/esr/meter-readings#

Objectif : Récupère les relevés bruts du compteur (valeurs d'index) pour le RTPL.

{
    "rtpl": "...",
    "since": "2026-02-23",
    "until": "2026-02-24",
    "type": "fournisseur"
}

{
    "rtpl": "...",
    "since": "2026-02-23",
    "until": "2026-02-24",
    "count": 4384,
    "data": [
        {
            "value": 77818,
            "measureType": "NETWORK_INDEX_02",
            "libelle": "GRD HP BASSE",
            "timestamp": "2026-02-23T00:00:00.000+00:00",
            "timestampStorage": "2026-02-23T00:41:02.079+00:00"
        },
        {
            "value": 37820,
            "measureType": "NETWORK_INDEX_03",
            "libelle": "GRD HC HAUTE",
            "timestamp": "2026-02-23T00:00:00.000+00:00",
            "timestampStorage": "2026-02-23T00:41:02.079+00:00"
        },
        {
            "value": 927210,
            "measureType": "NETWORK_INDEX_01",
            "libelle": "GRD HC BASSE",
            "timestamp": "2026-02-23T00:00:00.000+00:00",
            "timestampStorage": "2026-02-23T00:41:02.079+00:00"
        },
        {
            "value": 2897#63,
            "measureType": "NETWORK_INDEX_04",
            "libelle": "GRD HP HAUTE",
            "timestamp": "2026-02-23T00:00:00.000+00:00",
            "timestampStorage": "2026-02-23T00:41:02.079+00:00"
        }
    ]
}

POST/integration/esr/average-powers#

Objectif : Retourne la courbe de charge pour le RTPL, la direction et l'intervalle de temps demandés.

{
    "rtpl": "....",
    "since": "2026-01-22T23:00:00.000+00:00",
    "until": "2026-02-23T23:00:00.000+00:00",
    "type": "soutirage"
}

{
    "rtpl": "...",
    "count": 31,
    "since": "2026-01-22T23:00:00.000+00:00",
    "until": "2026-02-23T23:00:00.000+00:00",
    "data": [
        ...
    ]
}

RTPL de test pour l'intégration#

Les RTPL suivants sont disponibles pour tester différents types de contrats et scénarios de courbes de charge. Ces RTPL simulent le comportement réel d'ESR et vous permettent de valider votre intégration avec différentes configurations contractuelles.

Pour tous les cas de test suivants, vous devez d'abord créer un Ask pour le RTPL donné avec switchgrid-test-env à true, puis signer l'Ask vous-même.

1. C5 – Courbe de charge déjà activée#

Utilisez le RTPL suivant pour simuler un contrat C5 où la courbe de charge est déjà activée :

• RTPL : ESR00000C50001

Comportement attendu :

• L'appel à POST/integration/esr/average-powers réussit et retourne des données d'exemple (aléatoires).
• L'appel à POST/integration/esr/contract retourne des données contractuelles compatibles avec un C5.
• L'appel à POST/integration/esr/meter-readings réussit et retourne des données d'exemple (aléatoires).
• L'appel à POST/integration/esr/maximum-powers réussit et retourne des données d'exemple (aléatoires).

Ce scénario représente un point de livraison C5 pleinement opérationnel.

2. C5 – Courbe de charge en attente d'activation#

Utilisez le RTPL suivant pour simuler un contrat C5 où la courbe de charge doit être activée :

• RTPL : ESR00000C50002

Comportement attendu :

• L'appel à POST/integration/esr/average-powers retourne une erreur indiquant qu'ESR a été sollicité pour activer la courbe de charge, et que le processus d'activation peut prendre jusqu'à une semaine.

Ce scénario vous permet de valider la gestion des erreurs et la logique de retry pendant que la courbe de charge est en cours d'activation.

3. C4 – Contrat standard#

Utilisez le RTPL suivant pour simuler un contrat C4 :

• RTPL : ESR00000C40001

Comportement attendu :

• L'appel à POST/integration/esr/average-powers réussit et retourne des données d'exemple (aléatoires).
• L'appel à POST/integration/esr/contract retourne des données contractuelles compatibles avec un C4.
• L'appel à POST/integration/esr/meter-readings réussit et retourne des données d'exemple (aléatoires).
• L'appel à POST/integration/esr/maximum-powers réussit et retourne des données d'exemple (aléatoires).

Ce scénario représente un point de livraison C4 pleinement opérationnel.

Webhooks#

Les webhooks vous permettent de recevoir des notifications, par exemple lorsqu'un Ask est signé ou lorsqu'une commande dispose de nouvelles données.

Les webhooks sont des requêtes HTTP POST envoyées à l'adresse que vous définissez dans votre dashboard. Si le code de retour HTTP de votre serveur n'est pas 2xx, le système réessaiera de délivrer le webhook, jusqu'à 3 tentatives.

{
  "event": {
    "_tag": "order.request_success",
    "createdAt": "2024-09-17T10:21:32.262Z",
    "projectId": "a0efdd19-de68-480d-a92f-458ffd98f5c2",
    "orderId": "f720e25e-c662-402e-bd64-aa0771aa819f",
    "requestId": "de36dc27-ca90-4c10-ba6c-9524b1f9bcdf",
    "requestType": "R63"
  }
}

Tous les événements partagent les propriétés communes _tag, createdAt et projectId, complétées par des propriétés propres à chaque type.

Points importants#

Ce que Switchgrid gère#

• La vérification automatique de la correspondance entre le numéro de PRM/PDL (point de livraison) et le nom fourni lors du recueil de consentement. Si ceux-ci ne correspondent pas, Switchgrid ne pourra pas récupérer les données de consommation et indiquera pourquoi la vérification n'a pas abouti.
  • Exemple : le nom DUPONT est déclaré dans le formulaire, mais le contrat lié au PRM est au nom de MICHEL. La recherche dans le SI d'Enedis dans le sens « Adresse + Nom » → « PRM » ne ressort alors aucun résultat.
• Les échanges avec Enedis lors des contrôles réglementaires aléatoires, afin de prouver que nous disposons des mandats appropriés des utilisateurs finaux pour récolter leurs données de consommation.

Ce que Switchgrid ne gère pas#

• Les PRM hors du périmètre d'Enedis (par exemple les villes desservies par des gestionnaires de réseau locaux comme Strasbourg ou Grenoble).
• Les PRM dépourvus de compteur télérelevé.
• La vérification de l'identité de la personne (physique ou morale) qui remplit le formulaire de consentement.
• Lorsque la personne mandatée n'est pas le titulaire du contrat d'électricité (par exemple un proche, un employé d'entreprise, ou un syndic de copropriété) : le fait de s'assurer qu'elle est réellement autorisée à partager les données de consommation pour le nom donné.