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 /consent/{consentId} - Consulter un consentement utilisateur

• DELETE /consent/{consentId} - Révoquer un consentement

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 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. Si plusieurs contrats sont spécifiés, chaque PRM donnera son propre Consent (un consentId différent)
• 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.
 
• consentCollectionMedium décrit la façon dont le consentement doit être récupéré :
• WEB_HOSTED le consentement sera donné par la visite d’un parcours web (recommandé).
• DOCUSEAL le consentement sera donné par signature électronique
Aperçu d’un parcours web

 
Exemple de PDF de consentement envoyé pour signature électronique (via Docuseal)

• Le tableau scopes (optionnel) sera utilisé pour générer la section relative aux consentements dans le formulaire envoyé à l’utilisateur.



• Valeurs possibles pour scopes
• 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
• Le tableau purposes sera utilisé pour indiquer les finalités dans ce même formulaire



• Valeur possibles pour purposes
• SOLAR_INSTALLATION_SIZING
• DEMAND_RESPONSE
• ENERGY_PERFORMANCE_STUDY
• ENERGY_BROKERAGE
• VEHICLE_CHARGE_DETECTION
• signer : la personne qui remplit la déclaration de consentement. Que l’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": [
    {
      "prm": "00026555678579",
      "heldBy": {
        "name": "Société Test",
        "siret": "12345678901234"
      },
      "address": {
        "street": "1 rue de la Paix",
        "postalCode": "75001",
        "city": "Paris",
        "country": "France"
      }
    }
  ],
  "signer": {
    "email": "[email protected]",
    "genre": "M",
    "firstName": "Jean",
    "lastName": "lastName",
    "phone": "+33600000000"
  },
  "consentCollectionMedium": {
    "service": "DOCUSEAL",
  },
  "purposes": [ "SOLAR_INSTALLATION_SIZING" ],
  "consentDuration": "1 day"
}
 
En réponse (immédiatement), Switchgrid répond avec l’identifiant de un accusé de réception de l’Ask, ainsi que le lien du Docuseal à 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": "DOCUSEAL",
    "userUrl": "https://docuseal.co/s/x1uPBSwot114QM"
  },
  "consentIds": {},
  "createArgs": {...} # paramètres de création de l'Ask
}

Switchgrid procède alors à la vérification Nom / Adresse / PRM. Pour plus de détails voir
🔎
Comment Switchgrid vérifie la correspondance entre adresse et numéro de PDL/PRM (Point de Livraison)
Le client peut ensuite consulter à n’importe quel moment l’état de cet Ask en envoyant une requête sur l’endpoint GET /ask/{askId}
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 :
• 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
• consentIds contiendra, pour chaque PRM de l’Ask, un consentId.

{ 
	"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "ACCEPTED",
  ...
	"consentIds": {
    "00052775405049": "7252fa9f-b86a-4b95-a090-1012b730004c",
    "00088663455690": "2083c06a-2793-4475-affc-acfec79d4225"
  }
}

⚠️
Pour révoquer un consentement, vous aurez besoin du consentId . Le client a le droit de vous demander la révocation de son consentement. La révocation consiste en un simple appel à DELETE /consent/{consentId}. Une fois révoqué, le consentement ne peut plus servir à passer des commandes de données.

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

• consentId : le consentement à utiliser pour effectuer les requêtes

• 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	args	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é.	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…)	—	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.	direction: CONSUMPTION | INJECTION	JSON brut Enedis	1-2 minutes
R64_SYNC	Index quotidiens	direction since / until	JSON brut Enedis	< 10 secondes
R65_SYNC	Energies quotidiennes (en général obtenues par différence d’index)	direction since / until	JSON brut Enedis	< 10 secondes
R66_SYNC	Puissances max. quotidiennes	direction since / until	JSON brut Enedis	< 10 secondes
R67	Mesures facturantes	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)	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)	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.	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.	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.	direction since / until	JSON brut Enedis	~2-3 minutes

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]

 

 {
  "consentId": "47608cf7-1396-47fa-ada0-087de727b291",
  "requests": [
    {
      "type": "LOADCURVE",
      "direction": "CONSUMPTION",
      "since": "2024-06-12", // Optionnel
      "until": "2024-06-15"  // Optionnel
    },
    {
      "type": "R65"
    }
  ]
}

{
  "id": "47608cf7-1396-47fa-ada0-087de727b291",
  "status": "PENDING_ADDRESS_CHECK", # 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 
    }
  ]
}

Format des données transmises

GET /ask - Lister les Asks existants

• status

• prm

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
        ...
 }

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 endpoints accessibles

• GET /consent/{consentId} pour consulter un consentement utilisateur

• DELETE /consent/{consentId} pour annuler un consentement

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

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

Autres