Introduction#

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

Les endpoints suivants sont toujours accessibles sur app.switchgrid.tech/enedis/v2 :

GET/search_contract^enedis-v2 - rechercher un contrat d'électricité Enedis
POST/order^enedis-v2 - passer une commande pour Enedis

Nous fournirons progressivement des endpoints équivalents dans /v0_1, mais dès à présent, les demandes de consentement (asks) créées avec /v0_1 peuvent être utilisées avec les commandes /enedis/v2.

Voir le Guide API v2 pour la documentation de l'API spécifique à Enedis.

Authentification#

Tous les appels sont effectués avec un en-tête 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 l'en-tête 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"

⚠️

Attention, ce token API est un secret. Il permet de demander des données de consommation Enedis. Il est donc conseillé de ne pas le divulguer, et donc de faire les appels API depuis un serveur, et non depuis le navigateur ou un client mobile.

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 gaz et un contrat électricité provenant de GET/search_contract^enedis-v2 (ancien endpoint).

POST/ask

Authorization

Bearer

x-api-version

switchgrid-test-env

true

Corps

Saisissez un token pour envoyer des requêtes

Dépôt de justificatif de contrat#

Lorsque GET/search_contract^enedis-v2 (ancienne API) 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 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é.

Processus#

Créer un Ask

Créez un Ask via POST/ask comme d'habitude. Si le contrat ne peut pas être trouvé, le statut de l'Ask sera NOT_VALID et le statut du contrat sera NOT_FOUND.

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

ℹ️

Cela ne peut pas être utilisé avec les anciens Asks créés via POST/ask^enedis-v2.

Téléverser un justificatif de propriété

Téléversez une facture d'électricité pour le(s) contrat(s) en échec via POST/ask/{askId}/ownership_proof.

Envoyez une requête multipart/form-data avec le fichier justificatif (PDF ou image) dans le champ file.

⚠️

La facture doit être récente (moins de 3 mois) et doit contenir le numéro de PDL correspondant à celui fourni dans l'Ask.

Vérification

Switchgrid effectue une vérification manuelle ou automatique : nous vérifions que le PDL fourni par l'utilisateur apparaît dans le document, et que le titulaire du contrat et l'adresse correspondent au justificatif.

Pendant ces vérifications, le statut du ou des contrats de l'Ask est PENDING_PROOF_VERIFICATION.

Résultat

Une fois approuvé ou rejeté, un webhook est envoyé avec l'événement :

_tag: "proof.accepted" ou _tag: "proof.rejected"
Accompagné de askId et organizationId.

Si tout est correct, le contrat est validé et l'Ask poursuit son processus. Sinon, l'utilisateur est invité à vérifier ou à contacter le support.

Récupérer les données#

Une fois qu'un Ask est signé, vous pouvez commander des données :

depuis les anciens endpoints dans l'API enedis-v2
depuis les endpoints de cette version de l'API sous le chemin /integration, pour Enedis, GRDF et Strasbourg Électricité Réseaux. Voir les détails ci-dessous.

🧪

Nous travaillons actuellement sur de nouveaux endpoints version v0 pour permettre de collecter les données de manière unifiée à travers différentes sources de données. En attendant, vous pouvez utiliser les anciens endpoints Enedis avec des asks créés en v0, et pour GRDF et ESR, vous pouvez utiliser les endpoints impératifs décrits ci-dessous.

Enedis#

Il est toujours nécessaire d'utiliser /enedis/v2 (ancien endpoint) pour cela. Vous devez utiliser la syntaxe de commande avec prms dans chaque requête.

ℹ️

Note aux premiers utilisateurs de Switchgrid :

Pas besoin de spécifier un consentId, nous recherchons automatiquement les Asks correspondants dans l'ancienne et la nouvelle API.

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

GRDF#

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

ℹ️

Terminologie :

Ici nous utilisons le terme pce au lieu de deliveryPointId car cet endpoint est spécifique à GRDF, et c'est le vocabulaire de GRDF.

{
  "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.

Utilisation

Appelez cet endpoint pour récupérer les détails du contrat d'un client une fois que l'Ask de consentement est actif.

{
  "rtpl": "..."
}

Réponse

{
    "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.

Utilisation

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

Réponse

{
    "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.

Utilisation

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

Réponse

{
    "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.

❗

Activation de la courbe de charge C5 / C6

Pour les segments C5 et C6, la courbe de charge n'est pas activée par défaut lors du consentement. Nous demandons l'activation de la courbe de charge durant le processus de consentement (Ask), mais cela peut prendre jusqu'à une semaine avant que les données soient disponibles. En attendant :

Les appels à cet endpoint peuvent retourner une erreur indiquant que la courbe de charge n'est pas encore disponible.
Les clients doivent implémenter une stratégie de retry ou de vérification de statut en attendant que les données soient activées.

Utilisation

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

Réponse

{
    "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.

Introduction#

Authentification#

Collecter le consentement utilisateur#

Créez votre premier Ask avec POST/ask#

Dépôt de justificatif de contrat#

Processus#

Créer un Ask

Téléverser un justificatif de propriété

Vérification

Résultat

Récupérer les données#

Enedis#

GRDF#

Strasbourg Électricité Réseaux (ESR)#

Endpoints#

POST/integration/esr/contract#

POST/integration/esr/maximum-powers#

POST/integration/esr/meter-readings#

POST/integration/esr/average-powers#

RTPL de test pour l'intégration#

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

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

3. C4 – Contrat standard#

Créez votre premier `Ask` avec POST`/ask`#

POST`/integration/esr/contract`#

POST`/integration/esr/maximum-powers`#

POST`/integration/esr/meter-readings`#

POST`/integration/esr/average-powers`#