API Switchgrid Enedis

Introduction

Vocabulaire

Principaux endpoints

• GET /search_contract pour rechercher un contrat électrique à partir d’un nom et d’une adresse.

• POST /ask pour demander la récolte d’un consentement utilisateur (ou plusieurs si plusieurs PRMs)
• GET /ask/{askId} pour consulter l’état d’un Ask, et voir les Consents associés.

• POST /order un appel pour commander des données de consommation , à partir d’un Consent ou d’un Ask
• GET /order/{orderId} pour consulter l’état d’un Order et récolter les données associées après un temps variable en fonction du type de données (quelques secondes pour des informations contractuelles, quelques minutes pour une courbe de charge sur 24 mois)

• GET /request/{requestId}/data Pour récupérer les données des requêtes de type LOADCURVE.

Autres points accessibles

• GET /ask - Lister les Asks et leur état

• GET /order/{orderId} pour consulter l’état de la commande et récolter les données

• DELETE /ask/{askId} pour annuler un Ask, et tous les consentements associés

Authentification

Environnement de test (switchgrid-test-env)

Endpoints

GET /search_contract - Recherche de contrat

• La requête prend 2 paramètres obligatoires
• name, qui doit contenir au moins 3 caractères (ex: “Dupond” ou “Jeanne Dupond”, ou “SARL Les Tanneurs“)
• et au moins l’un des deux paramètres suivants:
• address qui doit contenir au moins un élément de nom de voie et un code postal. Par exemple : “1 rue de la paix 75002 Paris”
• prm le numéro de PDL (Point de Livraison)
La réponse ressemble à

{
    "results": [
        {
            "nomClientFinalOuDenominationSociale": "ST DUPONT",
            "prm": "00000000000022",
            "categorieClientFinalCode": "PRO",
            "adresseInstallationNormalisee": {
                "ligne2": "DP TJ TB",
                "ligne4": "10 RUE DE LA PAIX",
                "ligne6": "75002 PARIS"
            }
        }
    ]
}

POST /ask - Collecte de consentement

• Le corps de la requête est composé de :
• electricityContracts peut être de 2 types différents. Soit un tableau d’uuid - résultats de GET /search_contract (recommandé) - soit un tableau d’objets contenant les données relatives au(x) contrat(s) d’électricité dont pour lesquels on veut récupérer des données (voir spécification)
Format des contrats dans electricityContracts (inutile si vous utilisez GET /search_contract)
• heldBy : le titulaire du contrat d’électricité, peut être la même personne que signedBy dans le cas résidentiel. Dans le cas où c’est une personne différente, ou une entreprise, alors signedBy est mandaté(e) par electricityContract.heldBy.
• personne physique:
• genre, firstName, lastName
• personne morale
• name: dénomination sociale de l’entreprise
• siren: le SIREN de l’entreprise
• address : l’adresse où se situe le compteur électrique pour le PRM donné. Que ce soit pour un particulier ou une entreprise.
scopes (optionnel) peut être utilisé pour générer la section relative aux consentements dans le formulaire envoyé à l’utilisateur.

• Vous pouvez personnaliser scopes, c’est-à-dire les données auxquelles vous demandez accès. Par défaut ce sera toutes les données disponibles.
• service: ENEDIS_RAW_API
• id: DETAILS_CONTRACTUELS
• id: "CONSUMPTION_DATA"
• args
• types tableau d’une ou plusieurs valeurs (CDC, IDX, ENERGIE, PMAX)
• directions tableau contenant SOUTIRAGE, INJECTION ou les deux.
• Les codes types correspondent aux données suivantes chez Enedis

type	code des données Enedis	description
CDC	R63	Courbe de charge
IDX	R64	Index Quotidiens
ENERGIE	R65, R67	Energies Quotidiennes Mesures facturantes
PMAX	R66	Puissances Maximales quotidiennes
purposes (optionnel) sera utilisé pour indiquer les finalités dans ce même formulaire

• Valeur possibles pour purposes
• ENERGY_PERFORMANCE_STUDY (valeur par défaut) Étude de performance énergétique
• SOLAR_INSTALLATION_SIZING Dimensionnement d’une installation solaire
• DEMAND_RESPONSE Effacement de consommation électrique - Flexibilité électrique
• ENERGY_BROKERAGE Courtage en énergie
• VEHICLE_CHARGE_DETECTION Charge intelligente de véhicule électrique
• signer : la personne qui remplit la déclaration de consentement. Ce peut être le titulaire du/des compteurs, ou une personne mandatée par ce titulaire. On peut être amené à contacter en cas de litige, ou de demande de documents de preuve comme une facture d’électricité.
• consentDuration : Durée qui pendant laquelle les consentements pourront être utilisés, à partir de la date de signature du Ask.
{
  "electricityContracts": [
    "7401e757-2216-4cc5-8e51-e7176de67ed6"
  ],
  "signer": {
    "firstName": "Jean",
    "lastName": "lastName"
  },
  "purposes": [ "SOLAR_INSTALLATION_SIZING" ],
  "consentDuration": "3 years"
}
 
En réponse, Switchgrid répond avec l’identifiant de un accusé de réception de l’Ask, ainsi que le lien du formulaire à faire signer.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "PENDING_USER_ACTION", # Si la vérification d'adresse Enedis est un succès, sinon "ADDRESS_CHECK_FAILED"
  "acceptedAt": "2024-06-17T13:40:21.422Z",
  "consentCollectionDetails": {
    "service": "WEB_HOSTED",
    "userUrl": "https://app.switchgrid.tech/c/..."
  },
  "createArgs": {...} # paramètres de création de l'Ask
}



 
Le client peut consulter à n’importe quel moment l’état de cet Ask en envoyant une requête sur l’endpoint GET /ask/{askId}, pour notamment savoir s’il a été signé.
Parfois, des vérifications d’adresse (est-ce que le contrat existe toujours) sont effectuées. Une fois ces vérifications effectuées, consentCollectionDetails.userUrl contient une URL à donner à la personne qui doit signer le consentement.
• Dans le cas d’un consentement web (WEB_HOSTED), vous pouvez spécifier des paramètres d’url supplémentaires à l’URL fournie dans userUrl :
• redirectTo pour rediriger l’utilisateur une fois le consentement signé.
exemple d’URL valide : https://app.switchgrid.tech/c/ask/3fa85f64-5717-4562-b3fc-2c963f66afa6?redirectTo=https://my-solar-company.com/switchgrid/redirect
Une fois que le document de signature électronique a été signé, lors d’un appel à GET /ask/{askId}, status passe à ACCEPTED
⚠️
Pour révoquer un consentement préalablement signé, utilisez DELETE /ask/{askId}. Pour le moment, il n’est pas possible de révoquer seulement une partie des compteurs dans un Ask qui en possèderait plusieurs.

POST /order - Commande des données de consommation pour consentement préalablement reçu

• requests: une liste de requêtes (requests) pour lesquelles l’utilisateur final a donné son consentement libre et éclairé (via un formulaire papier / en ligne, un email ou un appel téléphonique). Nous supportons les valeurs suivantes :

Code	Description	arguments obligatoires	arguments optionnels	Format	Latence médiane
LOADCURVE	Courbe de charge en injection ou en soutirage. Utiliser GET /request/{requestId}/data pour récupérer les données à un pas spécifique et dans le format souhaité.	prms	direction since / until	Format Switchgrid (csv ou json)	< 2-3 secondes pour ≤ 7 jours ~2-3 minutes pour > 7 jours
C68	Les données contractuelles (puissance souscrite, heures creuses/heures pleines…)	prms	—	JSON brut Enedis	< 10 secondes
C68_ASYNC	Les données contractuelles (puissance souscrite, heures creuses/heures pleines…) - Plus complet que C68, supporte aussi les points en injection.	prms	direction: CONSUMPTION | INJECTION	JSON brut Enedis	1-2 minutes
R64_SYNC	Index quotidiens	prms	direction since / until	JSON brut Enedis	< 10 secondes
R65_SYNC	Energies quotidiennes (en général obtenues par différence d’index)	prms	direction since / until	JSON brut Enedis	< 10 secondes
R66_SYNC	Puissances max. quotidiennes	prms	direction since / until	JSON brut Enedis	< 10 secondes
R67	Mesures facturantes	prms	direction since / until	JSON brut Enedis	~2-3 minutes
R63	Note: Préférer LOADCURVE, à moins de vouloir le format Enedis brut. La courbe de charge en soutirage du site (par défaut pour la période des 24 derniers mois à la veille), au pas restitué par Enedis (en général 30 minutes pour les clients particuliers, 10 minutes pour les tertiaires)	prms	direction since / until	JSON brut Enedis	~2-3 minutes
R63_SYNC	Note: Préférer LOADCURVE, à moins de vouloir le format Enedis brut. La courbe de charge en soutirage du site (par défaut pour la période des 7 derniers jours à la veille), au pas restitué par Enedis (en général 30 minutes pour les clients particuliers, 10 minutes pour les tertiaires)	prms	direction since / until	JSON brut Enedis	< 10 secondes
R64	Index quotidiens (asynchrone) Note: Cette requête est proposée pour rétro-compatibilité, mais R64_SYNC sera plus rapide et plus efficace.	prms	direction since / until	JSON brut Enedis	~2-3 minutes
R65	énergies quoditiennes Note: Cette requête est proposée pour rétro-compatibilité, mais R64_SYNC sera plus rapide et plus efficace.	prms	direction since / until	JSON brut Enedis	~2-3 minutes
R66	Puissances maximales Note: Cette requête est proposée pour rétro-compatibilité, mais R64_SYNC sera plus rapide et plus efficace.	prms	direction since / until	JSON brut Enedis	~2-3 minutes

Exemples de fichiers bruts (format Enedis)
 
Les paramètres since et until sont par défault en UTC (si pas de timezone spécifiée). Ils peuvent prendre les formes suivantes :

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]

 

 {
  "requests": [
    {
	    "prms": ["00045855908792"], // Obligatoire
      "type": "LOADCURVE",
      "direction": "CONSUMPTION",
      "since": "2024-06-12", // Optionnel
      "until": "2024-06-15"  // Optionnel
    },
    {
	    "prms": ["00045855908792"], // Obligatoire
      "type": "R65"
    }
  ]
}

{
  "id": "47608cf7-1396-47fa-ada0-087de727b291",
  "status": "PENDING_REQUESTS", # Etat de l'order
  "requests": [
    {
      "type": "LOADCURVE",
      "status": "SUCCESS",
      "orderedAt": "2024-11-13T13:46:38.385Z",
      "completedAt": "2024-11-13T13:46:39.638Z",
      "errorMessage": null
    },
    {
		  "type": "R65",
      "status": "PENDING",
      "orderedAt": "2024-11-13T13:46:38.392Z",
      "completedAt": null,
      "errorMessage": null
    }
  ]
}

GET /order - Consultation d’une commande

{
  "id": "904ae72d-fd16-446c-914f-fd5ff3eca689",
  "status": "PENDING_ADDRESS_CHECK", # Etat de l'order
  "requests": [
    {
      "type": "C68",
      "status": "PENDING_ADDRESS_CHECK",
      "orderedAt": null,
      "completedAt": null
      "errorMessage": null
    },
    {
      "type": "R65",
      "status": "PENDING_ADDRESS_CHECK",
      "orderedAt": null,
      "completedAt": null,
      "errorMessage": null
    }
  ]
}

Différents états possibles de l’objet order (order.status)

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

Erreurs possibles

{
    "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",
            "loadCurve": null
        }
    ]
}

1. R63/LOADCURVE La demande ne peut aboutir : aucun service souscrit de courbe de charge n'est présent pour la période demandée (ou LOADCURVE [SGT4G3]: Aucune mesure trouvée sur ce point )
En général, cela signifie que la courbe de charge n’a jamais été collectée pour ce compteur. Dans ces cas là, nous faisons automatiquement et immédiatement la demande auprès d’Enedis d’activation de cette collecte quotidienne. Nous vous invitons à recréer un order identique quelques heures après ou le lendemain. Vous pourrez espérer récolter jusqu’à 3-4 mois de données historiques (stockées dans le compteur Linky).
👉

Vous pouvez utiliser l’option enedisRetryAfterLoadcurveActivation: true pour que Switchgrid rééssaye automatiquement la requête de courbe de charge si un tel événément survient. Dans ce cas, la requête peut rester plusieurs heure en statut PENDING le temps qu’Enedis nous remonte les données depuis le compteur.

 {
  "consentId": "47608cf7-1396-47fa-ada0-087de727b291",
  "requests": [
    {
      "type": "LOADCURVE",
      "direction": "CONSUMPTION",
      "enedisRetryAfterLoadcurveActivation": true 
    }
  ]
}

GET /request/{requestId}/data - Récupérer les données de LOADCURVE

Format CSV

startDate,powerInWatts
2024-12-15T23:00:00.000Z,321 // Puissance moyenne en watts entre 23:00:00Z et 23:10:00Z
2024-12-15T23:10:00.000Z,294 // Puissance moyenne en watts entre 23:10:00Z et 23:20:00Z

Format JSON

{
    "period": "PT600S",
    "startsAt": "2024-12-15T23:00:00.000Z",
    "endsAt": "2024-12-16T23:00:00.000Z",
    "values": [
        321, // Puissance moyenne en watts entre 23:00:00Z et 23:10:00Z
        294, // Puissance moyenne en watts entre 23:10:00Z et 23:20:00Z
        ...
 }

Récupération des données au format brut Enedis

GET /ask - Lister les Asks existants

• status

• prm

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 au moment du recueil de consentement. Attention, dans le cas où ceux-ci ne correspondent pas, alors Switchgrid ne pourra pas récupérer les données de consommation. Dans ce cas, Switchgrid indiquera pourquoi la vérification n’a pas été possible.
• exemple : dans le formulaire, le nom DUPONT est déclaré, mais le contrat lié au numéro de PRM du formulaire est MICHEL. Alors lorsqu’on fait une recherche dans le SI d’Enedis dans le sens “Adresse + Nom” > “Prm”, aucun résultat ne ressort.

• Les échanges avec Enedis lors des contrôles réglementaires aléatoires réalisés par Enedis afin de s’assurer du fait que nous avions les mandats appropriés des utilisateurs finaux pour récolter leurs données de consommation

Ce que Switchgrid ne gère pas

• Les PRM qui ne sont pas dans le périmètre d’Enedis (exemple : villes avec des GRD historiques locaux comme Strasbourg ou Grenoble)

• Les PRMs dépourvus de compteur télérelevé

• La vérification de l’identité de la personne (physique ou morale) remplissant le formulaire de consentement sur le site du client.

• Dans le cas où la personne mandatée n’est pas le titulaire du contrat d’électricité : (par exemple un proche, un employé dans le cas d’une entreprise, ou encore un syndic de copropriété) le fait de s’assurer que la personne mandatée est réellement autorisée à partager les données de consommation électrique pour le nom donné.

Webhooks

Format général

{
    "event": {
		    // Propriétés communes à tous les événements
        "_tag": "order.request_success",  // Contient le tag correspondant à l'événement en question
        "createdAt": "2024-09-17T10:21:32.262Z", // La date de création de l'événement
        "organizationId": "a0efdd19-de68-480d-a92f-458ffd98f5c2",
               
        // Propriétés spécifiques au type d'évenement
        "orderId": "f720e25e-c662-402e-bd64-aa0771aa819f",
        "requestType": "R63",
        "requestId": "de36dc27-ca90-4c10-ba6c-9524b1f9bcdf"
    }
}

Propriétés par tag d’événement

• ask.accepted - Signature d’un Ask
• askId

• order.request_success - Succès d’une requête, au sein d’un Order
• orderId
• requestType
• requestId

• order.request_failed - Echec d’une requête, au sein d’un Order
• orderId
• requestType
• requestId

Ressources

Autres