La nouvelle version de notre Webhook Entrant est actuellement en version préliminaire.

Cette page a été traduite de l'anglais. Certains termes techniques et abréviations restent en anglais pour maintenir la cohérence technique. Consulter la version originale en anglais.

Ce guide est conçu pour aider les développeurs à intégrer leurs appareils avec EnergyID en utilisant des webhooks. Les webhooks permettent à vos appareils d'envoyer directement des données de mesure à EnergyID.

Voici une explication étape par étape sur l'utilisation des webhooks EnergyID :

1. Informations d'Approvisionnement : Générez une clé et un secret d'approvisionnement, qui sont stockés sur l'appareil. Plusieurs appareils peuvent utiliser les mêmes informations d'approvisionnement tant que tous les appareils au sein de la même flotte d'approvisionnement ont un identifiant unique.

2. Approvisionnement de l'Appareil : L'appareil contacte EnergyID au point de terminaison https://hooks.energyid.eu/hello en utilisant la clé et le secret d'approvisionnement, ainsi que son identifiant unique.

   • Enregistrement de l'Appareil : Si l'appareil n'est pas encore enregistré auprès d'EnergyID, le point de terminaison /hello renverra un objet WebhookClaimInfo contenant un code de réclamation et une URL. Cette URL doit être affichée sur la page de configuration de l'appareil, permettant à l'utilisateur de cliquer dessus et de lier l'appareil à son dossier EnergyID.

   • Informations du Webhook : Une fois que l'appareil a été réclamé, le point de terminaison /hello renverra un objet WebhookConnectionInfo. Celui-ci contient l'URL du webhook, les en-têtes HTTP requis (y compris un jeton d'autorisation), et l'intervalle d'envoi autorisé pour la transmission de données à EnergyID.
     • L'uploadInterval est une valeur en secondes et dépend de l'abonnement EnergyID de l'utilisateur :
       • Gratuit : 86400 secondes (24 heures)
       • Premium : 900 secondes (15 minutes)
       • Module complémentaire temps réel : 60 secondes
3. Envoi de Données : Une fois que l'appareil a accès au webhook, il peut commencer à envoyer des données de mesure à l'URL du webhook fournie. Assurez-vous d'inclure les en-têtes HTTP requis dans chaque requête.

Mise à jour des Informations de Connexion : Le jeton d'autorisation inclus dans les informations de connexion est valide pendant 48 heures et doit être actualisé régulièrement. Nous recommandons d'interroger le point de terminaison /hello toutes les 24 heures pour renouveler le jeton et vérifier tout changement dans la politique du webhook.
Si l'appareil reçoit une réponse HTTP 401 lors de l'envoi de données, cela indique que le jeton a expiré et doit être renouvelé immédiatement.

Approvisionnement de l'Appareil

Point de terminaison :

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

En-têtes :

• X-Provisioning-Key : Votre clé d'approvisionnement.
• X-Provisioning-Secret : Votre secret d'approvisionnement.

Paramètres :

• deviceId : Identifiant unique (au sein de la flotte d'applications) pour l'appareil.
• deviceName : Nom d'appareil lisible par l'humain.
• firmwareVersion (optionnel) : Version du firmware.
• ipAddress (optionnel) : Adresse IP locale.
• macAddress (optionnel) : Adresse MAC.
• localDeviceUrl (optionnel) : URL pour la configuration de l'appareil sur le réseau local.

Exemple

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

{
  "deviceId": "",
  "deviceName": "Mon appareil"
}

Réponse de réclamation

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

Réponse d'informations du webhook

{
  "webhookUrl": "https://hooks.energyid.eu/webhook-in",
  "headers": {
    "authorization": "Bearer ",
    "x-twin-id": "00000000-0000-0000-0000-000000000000"
  },
  "webhookPolicy": {
    "uploadInterval": 60
  }
}

Envoi de Données

Une fois que l'appareil reçoit une URL de webhook, il peut commencer à envoyer des données. Pour ce faire, envoyez une requête POST à l'URL du webhook et incluez tous les en-têtes retournés lors du processus d'approvisionnement de l'appareil.

Les données doivent être envoyées dans un objet JSON clé-valeur simple. La clé ts (timestamp), qui représente l'horodatage des mesures sous forme de timestamp Unix (en secondes), est la seule clé requise.

Les autres clés représentent l'ID d'une métrique ou d'un capteur spécifique mesuré par l'appareil et leurs valeurs correspondantes. Certaines clés sont prédéfinies par EnergyID, comme décrit dans la liste ci-dessous.

Lorsque vous utilisez ces propriétés prédéfinies (comme 'gas', 'pv', 'el'), EnergyID reconnaît automatiquement le type de compteur ou de capteur qu'elles représentent, de sorte que les données envoyées avec ces clés seront immédiatement visibles et correctement catégorisées sans configuration supplémentaire.

Vous pouvez choisir d'autres clés, mais comme EnergyID ne sait pas ce que ces points de données représentent, l'utilisateur devra spécifier ces informations avant que les données ne deviennent visibles dans EnergyID.

Les clés prédéfinies peuvent également être utilisées comme préfixes (séparés par un point) lorsque plusieurs points de données du même type sont présents. Les données peuvent être envoyées soit comme un seul objet, soit comme une liste d'objets.

Exemple

POST

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

Propriétés Prédéfinies

Gestion des Erreurs

Il est recommandé de se préparer aux scénarios où les tentatives d'envoi d'une charge utile pourraient échouer. Les webhooks entrants peuvent renvoyer des erreurs pour des requêtes mal formées, des informations d'identification invalides, ou lorsqu'un événement exceptionnel nous empêche de stocker vos données.

Limitation de Débit (Rate Limiting)

L'API applique des limites de débit pour garantir une utilisation équitable. Si votre appareil envoie trop de requêtes dans un court laps de temps, le serveur répondra avec une erreur HTTP 429 Too Many Requests.

Lorsque cela se produit, vérifiez l'en-tête HTTP Retry-After dans la réponse. Cet en-tête contient le nombre de secondes que vous devez attendre avant de faire une autre requête. Pour éviter d'atteindre cette limite, il est recommandé de regrouper les données et d'exécuter votre processus moins fréquemment, par exemple toutes les 15 minutes.

Développer des Applications

Les fournisseurs de matériel et les fournisseurs de données cloud-to-cloud peuvent proposer leur propre intégration dans le répertoire d'applications EnergyID. Cela permet une expérience utilisateur plus fluide.

Au lieu d'utiliser des informations d'identification standard au niveau de l'utilisateur, les partenaires reçoivent une Clé et un Secret d'Approvisionnement de l'Appareil dédiés. Ceux-ci sont liés à un point de terminaison dédié pour votre application, offrant une solution robuste et évolutive à vos utilisateurs. Contactez-nous à info@energieid.be pour plus d'informations sur la manière de devenir un partenaire d'intégration.