Collection Postman : https://www.postman.com/thomas-carli/workspace/switchgrid-public/collection/4602012-cf6b568e-addb-41a9-868d-3e6cbd73eabe

Introduction#

Vocabulaire#

Principaux endpoints#

Les endpoints suivants permettront de recuperer les donnees d'un compteur electrique.

• GET /search_contract pour rechercher un contrat electrique a partir d'un nom et d'une adresse.
• POST /ask pour demander la recolte d'un consentement utilisateur (ou plusieurs si plusieurs PRMs)
  • GET /ask/{askId} pour consulter l'etat d'un Ask, et voir les Consents associes.
• POST /order un appel pour commander des donnees de consommation, a partir d'un Consent ou d'un Ask
  • GET /order/{orderId} pour consulter l'etat d'un Order et recolter les donnees associees apres un temps variable en fonction du type de donnees (quelques secondes pour des informations contractuelles, quelques minutes pour une courbe de charge sur 24 mois)
• GET /request/{requestId}/data Pour recuperer les donnees des requetes de type LOADCURVE.

Autres points accessibles#

• GET /ask - Lister les Asks et leur etat
• GET /order/{orderId} pour consulter l'etat de la commande et recolter les donnees
• DELETE /ask/{askId} pour annuler un Ask, et tous les consentements associes

Authentification#

Tous les appels sont effectues avec un header d'authentification contenant un jeton d'API, (fourni par Switchgrid via l'interface https://app.switchgrid.tech) du type Authorization: Bearer <Token>.

Environnement de test (switchgrid-test-env)#

Vous pouvez inclure le header suivant dans vos requetes de POST /ask : switchgrid-test-env: true pour que ceux-ci ne soient pas factures. Les orders qui en decoulent ne seront pas factures non plus, mais ils renverront des donnees factices.

Endpoints#

GET /search_contract#

La requete prend 2 parametres obligatoires :

• name, qui doit contenir au moins 3 caracteres (ex: "Dupond" ou "Jeanne Dupond", ou "SARL Les Tanneurs")
• et au moins l'un des deux parametres suivants :
  • address qui doit contenir au moins un element de nom de voie et un code postal. Par exemple : "1 rue de la paix 75002 Paris"
  • prm le numero de PDL (Point de Livraison)

Exemple de reponse :

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

POST /ask#

Le corps de la requete est compose de :

• electricityContracts peut etre de 2 types differents. Soit un tableau d'uuid - resultats de GET /search_contract (recommande) - soit un tableau d'objets contenant les donnees relatives au(x) contrat(s) d'electricite.

• scopes (optionnel) peut etre utilise pour generer la section relative aux consentements dans le formulaire.

• purposes (optionnel) sera utilise pour indiquer les finalites dans le formulaire

• signer : la personne qui remplit la declaration de consentement.
• consentDuration : Duree pendant laquelle les consentements pourront etre utilises, a partir de la date de signature du Ask.

Exemple de requete :

{
  "electricityContracts": ["7401e757-2216-4cc5-8e51-e7176de67ed6"],
  "signer": {
    "firstName": "Jean",
    "lastName": "lastName"
  },
  "purposes": ["SOLAR_INSTALLATION_SIZING"],
  "consentDuration": "3 years"
}

En reponse, Switchgrid repond avec l'identifiant et un accuse de reception de l'Ask, ainsi que le lien du formulaire a faire signer.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "PENDING_USER_ACTION",
  "acceptedAt": "2024-06-17T13:40:21.422Z",
  "consentCollectionDetails": {
    "service": "WEB_HOSTED",
    "userUrl": "https://app.switchgrid.tech/c/..."
  },
  "createArgs": {}
}

Dans le cas d'un consentement web (WEB_HOSTED), vous pouvez specifier des parametres d'url supplementaires a l'URL fournie dans userUrl :

• redirectTo pour rediriger l'utilisateur une fois le consentement signe.

Une fois que le document de signature electronique a ete signe, lors d'un appel a GET /ask/{askId}, status passe a ACCEPTED.

Pour revoquer un consentement prealablement signe, utilisez DELETE /ask/{askId}. Pour le moment, il n'est pas possible de revoquer seulement une partie des compteurs.

POST /order#

Une fois que l'utilisateur a donne son consentement via un Ask, il est possible de commander des donnees via POST /order.

• requests : une liste de requetes pour lesquelles l'utilisateur final a donne son consentement.

Types de requetes#

Les parametres since et until sont par defaut en UTC. 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]

Exemple de requete :

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

Reponse :

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

Muni d'un orderId, le client peut a tout moment savoir ou en est la/les requete(s) de donnees.

Exemple de reponse :

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

Si les champs dataUrl sont renseignes, alors les donnees sont disponibles a l'adresse indiquee, au format JSON.

Gestion des erreurs#

Exemple d'erreur :

{
  "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 present pour la periode demandee"
    }
  ]
}

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

GET /request/{requestId}/data#

Récuperer les donnees de LOADCURVE

Format CSV#

Les donnees renvoyees sont en heure UTC, et "pas commencant".

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

GET /ask#

Lister les Asks existants.

Vous pouvez filtrer selon les champs suivants : status, prm.

Pour plus de details, consulter la specification de l'API.

Points importants#

Ce que Switchgrid gere#

• La verification automatique de la correspondance entre le numero de PRM/PDL et le nom fourni au moment du recueil de consentement.
• Les echanges avec Enedis lors des controles reglementaires aleatoires.

Ce que Switchgrid ne gere pas#

• Les PRM qui ne sont pas dans le perimetre d'Enedis (villes avec des GRD historiques locaux comme Strasbourg ou Grenoble)
• Les PRMs depourvus de compteur telereleve
• La verification de l'identite de la personne remplissant le formulaire de consentement
• Dans le cas ou la personne mandatee n'est pas le titulaire du contrat : le fait de s'assurer que la personne mandatee est reellement autorisee.

Webhooks#

Les webhooks vous permettent de recevoir des notifications par exemple lorsqu'un Ask est signe, ou lorsqu'un Order a de nouvelles donnees disponibles.

Format general#

Les webhooks sont des requetes HTTP POST envoyees a l'adresse que vous definissez dans votre dashboard.

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

Proprietes par tag d'evenement#