diff --git a/docs/documents/egl-api-doc.pdf b/docs/documents/egl-api-doc.pdf new file mode 100644 index 0000000000000000000000000000000000000000..71c2ba0601454ae3b75e7ff3b9a5fa1b56496a4e Binary files /dev/null and b/docs/documents/egl-api-doc.pdf differ diff --git a/docs/ecolyo/konnectors/egl.md b/docs/ecolyo/konnectors/egl.md index 2f4f692dba5c6228a0130fccce621b4c7e2d7452..449222c70dbab7b1fcc1adbaca66ea81246357a1 100644 --- a/docs/ecolyo/konnectors/egl.md +++ b/docs/ecolyo/konnectors/egl.md @@ -1,2 +1,130 @@ !!! info "" - :construction: Section under Construction :construction: \ No newline at end of file +:construction: Section under Construction :construction: + +## EGL Konnector + +This konnector fetches consumptions measures from EGL API. +The EGL API allows us to get a user's consumption data gathered by it's connected water meter "Téléo". +You can clone the project [here](https://forge.grandlyon.com/web-et-numerique/llle_project/egl-konnector). + +You should also check Cozy's official documentations for konnectors : +[https://docs.cozy.io/en/tutorials/konnector/getting-started/](https://docs.cozy.io/en/tutorials/konnector/getting-started/) + +API Url for Development : [https://agence-rec.eaudugrandlyon.com](https://agence-rec.eaudugrandlyon.com/) + +API Url for Production : [https://agence.eaudugrandlyon.com/ws](https://agence.eaudugrandlyon.com/ws) + +## Authentication + +In order to authenticate to the EGL API we have to request the following route + +Method : **POST** + +Authentication Route : **/connect.asp** + +```json +"headers": +{ + { + "AuthKey": <your-auth-key>, + "Content-Type": "application/x-www-form-urlencoded" + } +} +``` + +```json +"body": +{ + "mode": "formdata" + { + "login": <your-login>, + "pass": <your-password> + } +} +``` + +Once you've sent this request the API should answer with a code 100 if everything is ok and provides you a valid **_token_** and **_num_abt_** that you will use later in order to get data. + +```json +{ + "codeRetour": 100, + "libelleRetour": "Connecté", + "resultatRetour": { + "num_abt": 1895683, + "token": "897555754A703055397897456568776E32704C3953514F5R" + } +} +``` + +## Fetch Data + +In order to get data from the EGL API we have to request the following route : + +Method : **POST** + +Authentication Route : **/getAllAgregatsByAbonnement.aspx** + +```json +"body": +{ + "mode": "formdata" + { + "login": <your-login>, + "pass": <your-password> + } +} +``` + +```json + +"body": +{ + "mode": "formdata" + { + "token": "897555754A703055397897456568776E32704C3953514F5R", + "num_abt": 1895683, + "date_debut": MM/JJ/YYYY, + "date_fin": MM/JJ/YYYY + } +} +``` + +The dates must be valid dates otherwise you'll get an error + +There answer will provides you an array of data day by day with the value got by the water meter 'ValeurIndex' at this moment. + +```json +{ + "codeRetour": 100, + "libelleRetour": "L'opération a réussi", + "resultatRetour": [ + { + "DateReleve": "2020-07-01T00:00:00+02:00", + "TypeAgregat": "R", + "ValeurIndex": 562362 + }, + { + "DateReleve": "2020-07-02T00:00:00+02:00", + "TypeAgregat": "R", + "ValeurIndex": 562432 + } + ] +} +``` + +You'll have to subtract a day value with the previous's to get a consumption for a given day. + +### TypeAgregats + +- "R", means the real value +- "A", means an anomaly +- "D", means a water meter changing +- "V" +- "X" +- "T", means pending data + +If you're looking for more information about the API, checkout the [complete API documentation](/documents/egl-api-doc.pdf) + +### Usage + +TODO : add explanation of how we manage data in the konnector diff --git a/docs/ecolyo/konnectors/enedis.md b/docs/ecolyo/konnectors/enedis.md index 2f4f692dba5c6228a0130fccce621b4c7e2d7452..ebc8cf40641e90d50b9abf53571d14151e590ac7 100644 --- a/docs/ecolyo/konnectors/enedis.md +++ b/docs/ecolyo/konnectors/enedis.md @@ -1,2 +1,39 @@ !!! info "" - :construction: Section under Construction :construction: \ No newline at end of file +:construction: Section under Construction :construction: + +This konnector fetches consumptions measures from Enedis API. This is an Oauth Konnector, meaning the authentification performed to access all data is made following an Oauth2 protocol. +You can clone the project [here](https://forge.grandlyon.com/web-et-numerique/llle_project/enedis-konnector). + +You should also check Cozy's official documentations for konnectors : +[https://docs.cozy.io/en/tutorials/konnector/getting-started/](https://docs.cozy.io/en/tutorials/konnector/getting-started/) +[https://docs.cozy.io/en/tutorials/konnector/oauth/](https://docs.cozy.io/en/tutorials/konnector/oauth/) + +## Enedis Konnector + +The Oauth protocol does not take place in the konnector code, therefore it is also important to take a look at the [proxy](../proxy/description.md) to fully understand all the interactions that will be told below. + +All the actions performed by the stack are targetted from pre-registered paramaters, here is the list of all parameters needed by the stack to perform the Oauth protocol and allow the konnector to fetch data. +On its first launch, following the Oauth Client Connect authentification. + +- The cozy stack calls the **authentification_endpoint** and start the oauth protocol, see [proxy doc](../proxy/description.md). +- The account has now an access_token and an id_token from the oauth call + +!!! info "" +id*token is only given when requesting the token endpoint in \_authorization_code* grant_type. +This token holds several meta datas, including the pce_id (id of user's meter) that will be needed further to fetch user's datas. + +- Konnector starts, fails to find a pce_id in database on first launch therefore decodes the id_token to store the pce_id in db (see [addData](https://docs.cozy.io/en/cozy-konnector-libs/api/#adddata_1)). +- Konnector restarts, this time knowing a pce_id, it fails to fetch datas because the access_token from oauth call has a reduced scope (only scoping for meta data requests). +- Konnector launches a refresh call, the proxy knows to answer it with a _client_credentials_ grant_type call to grdf /access_token. +- Konnector restarts with everyting needed in database to fetch datas and store them in couchdb. + +- Further jobs will not need to change scope again and will only ask for refresh tokens. + +## Enedis API + +API Url for Production : [https://gw.prd.api.enedis.fr](https://gw.prd.api.enedis.fr) + +Enpoints : + +- /v4/metering_data/consumption_load_curve +- /v4/metering_data/daily_consumption