Newer
Older
# Enedis SGE Konnector
This konnector fetches consumption measures from Enedis SGE SOAP API.
You should also check Cozy's official documentations for konnectors :
https://docs.cozy.io/en/tutorials/konnector/getting-started
The API used by this konnector are the one used by all energy providers (edf, total...), this one is supposed to have a high availability. Contrary to enedis oauth konnector, this is a regular auth konnector.
- xml2js: Lib allowing easy parsing to json
- easy-soap-request: Lib making soap request
### WSO2
For now enedis API are proxied by WSO2 api manager. You can find documentation and devportal [here](https://apis.grandlyon.fr/devportal).
- core/types: contains jsdoc types
- core/: requests wrapper with error handling logic
- helpers/ : contains helpers for aggregation, env and parsing
- requests/: contain all methods for : Parsing sge requests, Send/get backoffice data, interactions with cozy stack
- index.js: main file where default konnector methods are launch (start, ...)
- onDeleteAccount.js: hold consent suppression when a user delete an account. Automatically launched on delete.
### ts-check
In order to have better comfort while coding, we have enable ts-checking with vs-code. The verification is based on js-doc, please take time to maintain the js-doc.
:::info ts-check
The ts-check is none blocking. It will only put information in vs-code ide.
:::
In order to local test you have to copy the [konnector-dev-config.example.json](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/enedis-sge-konnector/-/blob/dev/konnector-dev-config.example.json?ref_type=heads) to `konnector-dev-config.json` and replace values and corresponding secrets.
:::warning user consent
While running in dev mode, be sure to have user consent, either on production env or with enedis standard form.
:::
You can now run the following commands to run the konnector :
```sh
yarn standalone # Run inside shell with no cozy env dependencies
yarn standalone-no-data # Run inside shell without getting any data
yarn dev # Run with your local cozy. For this one you need local stack to run
yarn onDeleteAccount:standalone # Run onDeleteAccount script
yarn onDeleteAccount # Run onDeleteAccount script with real cozy
For standalone cmd you can find konnector results in `/data/importedData.json`
| start | Main method of konnector. Handle global flow and init method with provided params |
| gatherData | Wrapper for getting daily, half-hour and max power data |
| getData | Get daily data |
| getMaxPowerData | Get daily Max Power data |
| getHalfHourData | Get half-hour data |
| getOffPeakHours | Get off-peak hours if activated in contract and store them in cozy.account |
| processData | Given a doctype, parse and format data before storing and aggregating |
| setStartDate | Save startDate with the right time range |
| storeData | Save data to user's cozy |
| agregateMonthAndYearData | Sum daily data for months and years |
| isFirstStart | Check if it's first start or an alternate start base on boId in cozy.account |
[Lien du schema](https://whimsical.com/sge-tech-DxbYM8DdajRjTr6WZat1bV)
#### Test with user invoices
To test user invoices, you will have to make a copy of `konnector-dev-config.example.json` to `konnector-dev-config.json` and fill out informations.
Then, to test the authentication flow of the konnector without fetching any data, launch the script `yarn standalone-no-data`
### Fetch Data
In order to get data from the SGE API we have to request the following route :
#### Get user contract startDate
Method : **POST**
Data Route : **enedis_SGE_ConsultationDonneesTechniquesContractuelles/1.0**
```xml
<soapenv:Body>
<v2:consulterDonneesTechniquesContractuelles>
<pointId>${pointId}</pointId>
<loginUtilisateur>${userLogin}</loginUtilisateur>
<autorisationClient>true</autorisationClient>
</v2:consulterDonneesTechniquesContractuelles>
</soapenv:Body>
```
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
Method : **POST**
Data Route : **enedis_SGE_ConsultationMesuresDetaillees/1.0**
```xml
<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:v2="http://www.enedis.fr/sge/b2b/services/consultationmesuresdetaillees/v2.0"
xmlns:v1="http://www.enedis.fr/sge/b2b/technique/v1.0">
<soapenv:Header/>
<soapenv:Body>
<v2:consulterMesuresDetaillees>
<demande>
<initiateurLogin>${appLogin}</initiateurLogin>
<pointId>${pointId}</pointId>
<mesuresTypeCode>${mesureType}</mesuresTypeCode>
<grandeurPhysique>${unit}</grandeurPhysique>
<soutirage>true</soutirage>
<injection>false</injection>
<dateDebut>${startDate}</dateDebut>
<dateFin>${endDate}</dateFin>
<mesuresCorrigees>false</mesuresCorrigees>
<accordClient>true</accordClient>
</demande>
</v2:consulterMesuresDetaillees>
</soapenv:Body>
</soapenv:Envelope>
```
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
#### Get Max Power data
Method : **POST**
Data Route : **enedis_SGE_ConsultationMesuresDetaillees/1.0**
```xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:v2="http://www.enedis.fr/sge/b2b/services/consultationmesuresdetaillees/v2.0"
xmlns:v1="http://www.enedis.fr/sge/b2b/technique/v1.0">
<soapenv:Header/>
<soapenv:Body>
<v2:consulterMesuresDetaillees>
<demande>
<initiateurLogin>${appLogin}</initiateurLogin>
<pointId>${pointId}</pointId>
<mesuresTypeCode>${mesureType}</mesuresTypeCode>
<grandeurPhysique>${unit}</grandeurPhysique>
<soutirage>true</soutirage>
<injection>false</injection>
<dateDebut>${startDate}</dateDebut>
<dateFin>${endDate}</dateFin>
<mesuresPas>P1D</mesuresPas>
<mesuresCorrigees>false</mesuresCorrigees>
<accordClient>true</accordClient>
</demande>
</v2:consulterMesuresDetaillees>
</soapenv:Body>
</soapenv:Envelope>
```
#### Get contract information
Method : **POST**
Data Route : **enedis_SGE_enedis_SGE_ConsultationDonneesTechniquesContractuelles/1.0**
This route also gives off-peak hours, if the user chose a contract with off-peak hours
```xml
<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:v2="http://www.enedis.fr/sge/b2b/services/consulterdonneestechniquescontractuelles/v1.0"
xmlns:v1="http://www.enedis.fr/sge/b2b/technique/v1.0">
<soapenv:Header/>
<soapenv:Body>
<v2:consulterDonneesTechniquesContractuelles>
<pointId>${pointId}</pointId>
<loginUtilisateur>${appLogin}</loginUtilisateur>
<autorisationClient>true</autorisationClient>
</v2:consulterDonneesTechniquesContractuelles>
</soapenv:Body>
</soapenv:Envelope>
```
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
Response :
```xml
<point id="12345678912345">
<donneesGenerales>
<etatContractuel code="SERVC">
<libelle>En service</libelle>
</etatContractuel>
<adresseInstallation>
<numeroEtNomVoie>208 BIS RUE GARIBALDI</numeroEtNomVoie>
<codePostal>69003</codePostal>
<commune code="69383">
<libelle>LYON 3</libelle>
</commune>
</adresseInstallation>
<niveauOuvertureServices>2</niveauOuvertureServices>
</donneesGenerales>
<situationComptage>
<dispositifComptage>
<relais>
<plageHeuresCreuses>HC (22H00-6H00)</plageHeuresCreuses>
</relais>
</dispositifComptage>
</situationComptage>
</point>
```
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
Method : **POST**
Data Route : **enedis_SGE_RechercheServicesMesures/1.0**
```xml
<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:v2="http://www.enedis.fr/sge/b2b/services/rechercherpoint/v2.0"
xmlns:v1="http://www.enedis.fr/sge/b2b/technique/v1.0">
<soapenv:Header/>
<soapenv:Body>
<v2:rechercherPoint>
<criteres>
<adresseInstallation>
<numeroEtNomVoie>${address}</numeroEtNomVoie>
<codePostal>${postalCode}</codePostal>
<codeInseeCommune>${inseeCode}</codeInseeCommune>
</adresseInstallation>
<nomClientFinalOuDenominationSociale>${name}</nomClientFinalOuDenominationSociale>
<rechercheHorsPerimetre>true</rechercheHorsPerimetre>
</criteres>
<loginUtilisateur>${appLogin}</loginUtilisateur>
</v2:rechercherPoint>
</soapenv:Body>
</soapenv:Envelope>
```
#### Get User services subscriptions
Method : **POST**
Data Route : **enedis_SGE_RechercheServicesMesures/1.0**
```xml
<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:v2="http://www.enedis.fr/sge/b2b/rechercherservicessouscritsmesures/v1.0"
xmlns:v1="http://www.enedis.fr/sge/b2b/technique/v1.0">
<soapenv:Header/>
<soapenv:Body>
<v2:rechercherServicesSouscritsMesures>
<criteres>
<pointId>${pointId}</pointId>
<contratId>${contractId}</contratId>
</criteres>
<loginUtilisateur>${appLogin}</loginUtilisateur>
</v2:rechercherServicesSouscritsMesures>
</soapenv:Body>
</soapenv:Envelope>
```
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
Method : **POST**
Data Route : **enedis_SGE_CommandeCollectePublicationMesures/1.0**
```xml
<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:v2="http://www.enedis.fr/sge/b2b/commandercollectepublicationmesures/v3.0"
xmlns:v1="http://www.enedis.fr/sge/b2b/technique/v1.0">
<soapenv:Header/>
<soapenv:Body>
<v2:commanderCollectePublicationMesures>
<demande>
<donneesGenerales>
<objetCode>AME</objetCode>
<pointId>${pointId}</pointId>
<initiateurLogin>${appLogin}</initiateurLogin>
<contratId>${contractId}</contratId>
</donneesGenerales>
<accesMesures>
<dateDebut>${startDate}</dateDebut>
<dateFin>${endDate}</dateFin>
<declarationAccordClient>
<accord>true</accord>
<personnePhysique>
<nom>${name}</nom>
</personnePhysique>
</declarationAccordClient>
<mesuresTypeCode>CDC</mesuresTypeCode>
<soutirage>true</soutirage>
<injection>false</injection>
<mesuresPas>PT30M</mesuresPas>
<mesuresCorrigees>false</mesuresCorrigees>
<transmissionRecurrente>true</transmissionRecurrente>
<periodiciteTransmission>P1D</periodiciteTransmission>
</accesMesures>
</demande>
</v2:commanderCollectePublicationMesures>
</soapenv:Body>
</soapenv:Envelope>
```
#### Stop User contract
```xml
<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:v2="http://www.enedis.fr/sge/b2b/commanderarretservicesouscritmesures/v1.0"
xmlns:v1="http://www.enedis.fr/sge/b2b/technique/v1.0">
<soapenv:Header/>
<soapenv:Body>
<v2:commanderArretServiceSouscritMesures>
<demande>
<donneesGenerales>
<objetCode>ASS</objetCode>
<pointId>${pointId}</pointId>
<initiateurLogin>${appLogin}</initiateurLogin>
<contratId>${contractId}</contratId>
</donneesGenerales>
<arretServiceSouscrit>
<serviceSouscritId>${serviceSouscritId}</serviceSouscritId>
</arretServiceSouscrit>
</demande>
</v2:commanderArretServiceSouscritMesures>
</soapenv:Body>
</soapenv:Envelope>
```
The same endpoint is used to get the data. The soap body is the following:
Method : **POST**
Data Route : **enedis_SGE_ConsultationDonneesTechniquesContractuelles/1.0**
```xml
<soapenv:Body>
<v2:consulterMesuresDetaillees>
<demande>
<initiateurLogin>${userLogin}</initiateurLogin>
<pointId>${pointId}</pointId>
<mesuresTypeCode>${mesureType}</mesuresTypeCode>
<grandeurPhysique>${unit}</grandeurPhysique>
<soutirage>true</soutirage>
<injection>false</injection>
<dateDebut>${startDt}</dateDebut>
<dateFin>${endDt}</dateFin>
<mesuresCorrigees>false</mesuresCorrigees>
<accordClient>true</accordClient>
</demande>
</v2:consulterMesuresDetaillees>
</soapenv:Body>
```
### Known Issues
#### Contract deletion and creation on same day
If you stop a contract on a day, (for exemple 8/08/22), you cannot start a new contract for this date with [start contract route](./enedis-sge.md#user_contract_start). You have to wait for the next day. This might cause some production issues
#### User data collect opposition
Users can remove consent from enedis account on data collecting. This will return the following when checking contracts.
```xml
<serviceSouscritMesures>
<serviceSouscritId>74472322</serviceSouscritId>
<pointId>19176410771132</pointId>
<serviceSouscritType code="OPPENR"/>
<serviceSouscritLibelle>Opposition à l'enregistrement de la courbe de charge</serviceSouscritLibelle>
<injection>false</injection>
<soutirage>true</soutirage>
<etatCode>ACTIF</etatCode>
<dateDebut>2022-06-24+02:00</dateDebut>
<dateFin>2022-08-10+02:00</dateFin>
<motifFinLibelle>Arrêt par le client</motifFinLibelle>
</serviceSouscritMesures>
```
We cannot override that, the only solution is to tell the user to activate data collect on [enedis](https://mon-compte-particulier.enedis.fr/donnees/).