Ce guide est concu pour aider les developpeurs a integrer leurs appareils avec EnergyID en utilisant des webhooks. Les webhooks permettent a vos appareils d'envoyer des donnees de mesure directement a EnergyID.

Voici une explication etape par etape de l'utilisation des webhooks EnergyID :

1. Identifiants de provisionnement : Generez une cle et un secret de provisionnement, qui sont stockes sur l'appareil. Plusieurs appareils peuvent utiliser les memes identifiants de provisionnement a condition que chaque appareil au sein de la meme flotte de provisionnement ait un identifiant unique.

2. Provisionnement de l'appareil : L'appareil contacte EnergyID au point de terminaison https://hooks.energyid.eu/hello en utilisant la cle et le secret de provisionnement, ainsi que son identifiant unique.

   • Enregistrement de l'appareil : Si l'appareil n'est pas encore enregistre aupres d'EnergyID, le point de terminaison /hello renverra un objet WebhookClaimInfo contenant un code de revendication et une URL. Cette URL doit etre affichee sur la page de configuration de l'appareil, permettant a l'utilisateur de cliquer dessus pour lier l'appareil a son dossier EnergyID. L'appareil doit interroger le point de terminaison /hello periodiquement (par ex. toutes les 30 secondes) jusqu'a ce que la reponse passe au format revendique.

   • Informations du webhook : Une fois l'appareil revendique, le point de terminaison /hello renverra un objet WebhookConnectionInfo. Celui-ci contient l'URL du webhook, les en-tetes HTTP requis (y compris un jeton d'autorisation), la politique du webhook et des informations sur le dossier EnergyID lie.
     • L'uploadInterval est une valeur en secondes qui depend de l'abonnement EnergyID de l'utilisateur :
       • Gratuit : 86400 secondes (24 heures)
       • Premium : 900 secondes (15 minutes)
       • Module temps reel : 60 secondes
3. Envoi de donnees : Une fois que l'appareil a acces au webhook, il peut commencer a envoyer des donnees de mesure a l'URL du webhook fournie. Incluez tous les en-tetes retournes lors du provisionnement de l'appareil exactement tels qu'ils ont ete recus. Les donnees peuvent etre envoyees sous forme d'un objet JSON unique ou d'un tableau JSON d'objets pour les envois par lots.

Mise a jour des informations de connexion : Le jeton d'autorisation inclus dans les informations de connexion est valide pendant 48 heures et doit etre renouvele regulierement. Nous recommandons d'interroger le point de terminaison /hello toutes les 24 heures pour renouveler le jeton et verifier les modifications de la politique du webhook. Toutes les valeurs stockees (URL du webhook, authorization, x-twin-id) doivent etre mises a jour a chaque renouvellement, car chacune d'entre elles peut changer.
Si l'appareil recoit une reponse HTTP 401 lors de l'envoi de donnees, cela indique que le jeton a expire et doit etre renouvele immediatement en appelant a nouveau /hello.

Provisionnement de l'appareil

Point de terminaison :

POST https://hooks.energyid.eu/hello

En-tetes :

• X-Provisioning-Key : Votre cle de provisionnement.
• X-Provisioning-Secret : Votre secret de provisionnement.

Parametres :

• deviceId : Identifiant unique (au sein de la flotte) pour l'appareil.
• deviceName : Nom lisible de l'appareil.
• firmwareVersion (optionnel) : Version du firmware.
• ipAddress (optionnel) : Adresse IP locale.
• macAddress (optionnel) : Adresse MAC.
• localDeviceUrl (optionnel) : URL pour la configuration de l'appareil dans le reseau local.

Exemple

POST https://hooks.energyid.eu/hello

{
  "deviceId": "00000000-0000-0000-0000-000000000000",
  "deviceName": "My device"
}

Reponse de revendication

{
  "claimCode": "4H7A70",
  "claimUrl": "https://app.energyid.eu/integrations/webhook-in/new?code=4H7A70",
  "exp": 1691402519
}

Lorsqu'un appareil recoit une reponse de revendication, il doit afficher la claimUrl a l'utilisateur et continuer a interroger le point de terminaison /hello a intervalles reguliers (par ex. toutes les 30 secondes) jusqu'a ce que la reponse contienne un webhookUrl, indiquant que l'appareil a ete revendique.

Reponse avec informations du webhook

{
  "webhookUrl": "https://hooks.energyid.eu/webhook-in",
  "headers": {
    "authorization": "SharedAccessSignature sr=...",
    "x-twin-id": "00000000-0000-0000-0000-000000000000"
  },
  "webhookPolicy": {
    "uploadInterval": 60
  },
  "recordName": "My home",
  "recordNumber": "EA-12345678"
}

Les champs recordName et recordNumber identifient le dossier EnergyID auquel l'appareil a ete lie. Ceux-ci peuvent etre affiches a l'utilisateur pour confirmation.

Envoi de donnees

Une fois que l'appareil a recu une URL de webhook, il peut commencer a envoyer des donnees. Pour cela, envoyez une requete POST a l'URL du webhook et incluez tous les en-tetes retournes lors du provisionnement. Transmettez les en-tetes authorization et x-twin-id exactement tels qu'ils ont ete recus de /hello. Ne les decodez pas, ne les reencodez pas et ne les modifiez pas.

Les donnees doivent etre envoyees sous forme d'un objet JSON cle-valeur simple. La cle ts, qui represente l'horodatage des mesures sous forme de timestamp Unix (en secondes), est la seule cle obligatoire.

Les autres cles representent l'identifiant d'une metrique ou d'un capteur specifique mesure par l'appareil et leurs valeurs correspondantes. Certaines cles sont predefinies par EnergyID, comme decrit dans la liste ci-dessous.

Lors de l'utilisation de ces proprietes predefinies (comme 'gas', 'pv', 'el'), EnergyID reconnait automatiquement le type de compteur ou de capteur qu'elles representent. Les donnees envoyees avec ces cles seront immediatement visibles et correctement categorisees sans configuration supplementaire.

Vous pouvez choisir d'autres cles, mais comme EnergyID ne sait pas ce que ces points de donnees representent, l'utilisateur devra specifier ces informations avant que les donnees ne deviennent visibles dans EnergyID.

Les cles predefinies peuvent egalement etre utilisees comme prefixes (separes par un point) lorsque plusieurs points de donnees du meme type sont presents.

Mesure unique

POST {webhookUrl}

{
  "ts": 1733835004,
  "gas": 1594.78,
  "pv": 35461.45,
  "el.t1": 11250,
  "el-i.t1": 1545,
  "el.t2": 8944,
  "el-i.t2": 6577,
  "my-custom-sensor": 544.22
}

Envoi par lots (tableau JSON)

Les donnees peuvent egalement etre envoyees sous forme d'un tableau JSON d'objets. C'est l'approche recommandee pour les appareils qui collectent des mesures frequemment, car cela reduit le nombre d'appels API et evite les limites de debit.

POST {webhookUrl}

[
  { "ts": 1733834704, "el": 12345.67, "pv": 3.10 },
  { "ts": 1733834764, "el": 12346.12, "pv": 3.25 },
  { "ts": 1733834824, "el": 12346.89, "pv": 3.40 }
]

Bonne pratique pour les lots : Collectez les mesures des capteurs dans un tampon et envoyez-les sous forme de tableau JSON a un intervalle correspondant a l'uploadInterval de la reponse /hello. Cela evite les erreurs de limite de debit 429 et est plus efficace que d'envoyer chaque mesure individuellement.

Proprietes predefinies

Gestion des erreurs

Il est recommande de prevoir les scenarios ou l'envoi de donnees pourrait echouer. Les webhooks entrants peuvent retourner des erreurs pour des requetes malformees, des identifiants invalides, ou lorsqu'un probleme exceptionnel nous empeche de stocker vos donnees.

Limitation de debit

L'API impose des limites de debit pour garantir une utilisation equitable. Si votre appareil envoie trop de requetes en peu de temps, le serveur repondra avec une erreur HTTP 429 Too Many Requests.

Lorsque cela se produit, verifiez l'en-tete HTTP Retry-After dans la reponse. Cet en-tete contient le nombre de secondes a attendre avant d'effectuer une nouvelle requete. Pour eviter d'atteindre cette limite, regroupez vos mesures dans un tableau JSON et envoyez-les a un intervalle correspondant a l'uploadInterval de la reponse /hello.

Exemples

Des exemples d'integration fonctionnels sont disponibles dans le dossier demos de la bibliotheque Python :

• cURL / bash : curl_examples.sh - Flux complet en HTTP brut : authentification, envoi d'une mesure unique, envoi par lots, renouvellement du jeton.
• Node-RED : nodered_flow.json - Flux importable avec authentification, nouvelle tentative de revendication, envoi unique, mise en tampon par lots et support multi-appareils.
• Python : Installez pip install energyid-webhooks et consultez le notebook de demarrage rapide ou le notebook de demo complet.

Developper des applications

Les fournisseurs de materiel et les fournisseurs de donnees cloud-to-cloud peuvent proposer leur propre integration dans le repertoire d'applications EnergyID. Cela permet une experience utilisateur plus fluide.

Au lieu d'utiliser des identifiants utilisateur standard, les partenaires recoivent une cle et un secret de provisionnement d'appareil dedies. Ceux-ci sont lies a un point de terminaison dedie pour votre application, offrant une solution robuste et evolutive pour vos utilisateurs. Contactez-nous a info@energieid.be pour plus d'informations sur le partenariat d'integration.