From 330cbe141089643119984b7dbd9e74b6976ec17d Mon Sep 17 00:00:00 2001
From: Pierre Ecarlat <pecarlat@grandlyon.com>
Date: Mon, 16 Dec 2024 12:44:33 +0000
Subject: [PATCH] feat: Add EGL efluid API documentation
---
docs/konnectors/egl-efluid.md | 120 ++++++++++++++++++++++
docs/konnectors/{egl.md => egl-veolia.md} | 10 +-
2 files changed, 128 insertions(+), 2 deletions(-)
create mode 100644 docs/konnectors/egl-efluid.md
rename docs/konnectors/{egl.md => egl-veolia.md} (90%)
diff --git a/docs/konnectors/egl-efluid.md b/docs/konnectors/egl-efluid.md
new file mode 100644
index 0000000..13e3a5e
--- /dev/null
+++ b/docs/konnectors/egl-efluid.md
@@ -0,0 +1,120 @@
+# EGL - efluid API (2025)
+
+[EGL repository](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/egl-konnector).
+
+This konnector fetches consumption measures from the efluid API from EGL.
+The EGL API allows us to get a user's consumption data gathered by it's connected water meter "Téléo".
+
+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://prepro-epgl-ecolyo-efluidconnect.multield.net](https://prepro-epgl-ecolyo-efluidconnect.multield.net)
+- API Url for Production : Not defined yet
+
+## Update or create data
+
+This konnector updates data if it has changed since the last execution or creates a new entry if the data is new. It also updates month and year aggregates except for start month and start year to prevent overriding data if user has more than 3 years of data.
+
+For this we use a combinaison of the hydrateAndFilter function and the updateOrCreate function.
+
+## Authentication
+
+In order to authenticate to the EGL API we have to request the following route
+
+Method : **POST**
+
+Authentication Route : **/login**
+
+```json
+"body":
+{
+ "user": "<epgl-user>",
+ "password": "<epgl-password>"
+}
+```
+
+Once you've sent this request the API should answer with a code 200 and a token in the response header, under the variable name `EFLUIDCONNECT_TOKEN`.
+
+## Identification
+
+Using the `EFLUIDCONNECT_TOKEN` header, the path to identify the user is available
+
+Method : **POST**
+
+Authentication Route : **/acteurs/rechercherClientParCompteur**
+
+```json
+"body":
+{
+ "refContrat": "<contract-number>",
+ "refCompteur": "<metering-id>"
+}
+```
+
+This path returns either:
+
+- `Status 200`: If the contract number does match the metering ID
+- `Error 500`: If they do **not** match
+
+## Fetch Data
+
+:::warning
+The earliest data that can be fetched is January 2024 due to the novelty of the API
+:::
+
+This path still requires `EFLUIDCONNECT_TOKEN` header
+
+Method : **POST**
+
+Data Route : **/contrats/consommationsJournalieres**
+
+```json
+
+"body":
+{
+ "refContrat": "<contract-number>",
+ "refCompteur": "<metering-id>",
+ "dateDebut": "2023-12-31T22:00:00.000Z",
+ "dateFin": "2024-12-31T22:00:00.000Z"
+}
+```
+
+The dates must be valid dates otherwise you'll get an error. They also should be in GMT-1.
+
+The answer will provide you an array of data day by day with the value got by the water meter 'consommation'. The month value in the response data goes with values from 0 to 11. An example of the returned format with two days fetched can be found below:
+
+```json
+{
+ "postes": [
+ {
+ "libelle": "toutes heures",
+ "data": [
+ {
+ "consommation": 654,
+ "index": 12645,
+ "debitMin": 20,
+ "volumeEstimeFuite": 30,
+ "jour": 1,
+ "mois": 1,
+ "annee": 2024
+ },
+ {
+ "consommation": 600,
+ "index": 13245,
+ "debitMin": 20,
+ "volumeEstimeFuite": 30,
+ "jour": 2,
+ "mois": 1,
+ "annee": 2024
+ }
+ ]
+ }
+ ],
+ "unites": {
+ "consommation": "m3",
+ "index": "m3",
+ "debitMin": "L/h",
+ "volumeEstimeFuite": "L"
+ }
+}
+```
diff --git a/docs/konnectors/egl.md b/docs/konnectors/egl-veolia.md
similarity index 90%
rename from docs/konnectors/egl.md
rename to docs/konnectors/egl-veolia.md
index 8610323..f508004 100644
--- a/docs/konnectors/egl.md
+++ b/docs/konnectors/egl-veolia.md
@@ -1,6 +1,12 @@
-# EGL
+# EGL - Veolia API (2024)
-[EGL repository](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/egl-konnector).
+:::danger Deprecated version
+
+This documentation details the technical implementation of the old konnector for EGL, using the Veolia API. A new version has been made based on the Efluid API, that planned to be released starting January 2025.
+
+:::
+
+[EGL repository, version v1.3.1](https://forge.grandlyon.com/web-et-numerique/factory/llle_project/egl-konnector/-/tree/v1.3.1).
This konnector fetches consumption 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".
--
GitLab