Comment intégrer les données d'humidité du sol SoilSense avec notre API et nos webhooks

La plupart des systèmes de capteurs d'humidité du sol sont un système fermé : vos données entrent, mais les récupérer pour vos propres outils passe au second plan. SoilSense voit les choses à l'inverse. SoilSense propose une API REST facile à utiliser et des webhooks en temps réel, pour que vos données d'humidité du sol puissent alimenter n'importe quel système que vous exploitez déjà — logiciel de gestion agricole, tableaux de bord BI, contrôleurs d'irrigation ou une simple feuille de calcul.

Ce guide explique comment connecter SoilSense à vos propres systèmes, avec des exemples concrets à la fois pour récupérer les données à la demande et pour vous les faire envoyer dès qu'elles arrivent.

Ce à quoi vous pouvez accéder

Une fois vos données ouvertes, les mesures que vos capteurs collectent deviennent des briques que vous pouvez utiliser partout. Via l'API, vous pouvez lire :

• La teneur en eau volumétrique (humidité du sol) à chaque profondeur de capteur
• La température du sol et la salinité
• L'eau disponible pour les plantes (PAW) — l'indicateur qui vous dit vraiment quand irriguer
• Les précipitations issues des pluviomètres connectés
• Votre exploitation et vos sites d'observation, leur configuration et tout l'historique des mesures
• La dernière mesure de n'importe quel site, pour des vérifications d'état en temps réel

Ce sont les mêmes données que celles affichées dans le tableau de bord SoilSense, disponibles de façon programmatique.

Étape 1 : créez une clé API

L'API utilise une authentification simple par clé API. Créez une clé dans les paramètres de votre compte SoilSense et traitez-la comme un mot de passe — gardez-la secrète et hors du code côté client et des dépôts publics.

Chaque requête transporte la clé dans un en-tête x-api-key. C'est toute l'authentification : pas de valse OAuth, aucun jeton à rafraîchir.

Étape 2 : votre première requête

Une clé en main, une requête tient sur une seule ligne. La voici avec curl, pour lire les détails de votre exploitation :

curl https://api.app.soilsense.io/api/farm \
  -H "x-api-key: $SOILSENSE_API_KEY"

Le même appel depuis JavaScript :

const res = await fetch("https://api.app.soilsense.io/api/farm", {
  headers: { "x-api-key": process.env.SOILSENSE_API_KEY },
});

const farm = await res.json();
console.log(farm);

Chaque endpoint suit exactement cette forme — seul le chemin change. GET /api/farm/sites liste vos sites d'observation et leurs identifiants ; à partir de là, GET /api/site/{siteId}/observations/latest renvoie la mesure la plus récente, /observations tout l'historique et /precipitation les données des pluviomètres connectés. La référence de l'API documente chaque endpoint avec ses paramètres exacts.

Étape 3 : travaillez avec les données

Les réponses reviennent sous forme de JSON propre, si bien que vous pouvez les glisser directement dans ce que vous construisez. Une réponse contenant la dernière mesure ressemble à peu près à ceci :

{
  "timestamp": 1640995200000,
  "rssi": -75,
  "data": {
    "top": {
      "volumetricWaterContent": 25.5,
      "temperature": 18.5,
      "plantAvailableWater": 75.2,
      "salinity": 0.45
    }
  }
}

Les mesures sont regroupées par profondeur de capteur (top, mid, midBot, bot), avec timestamp en millisecondes depuis l'epoch et les valeurs d'humidité en pourcentage. À partir de là, c'est du code ordinaire. Ajoutez la ligne à une base de données, publiez-la sur un canal Slack quand la PAW passe sous un seuil, écrivez-la dans un Google Sheet ou transmettez-la à votre contrôleur d'irrigation. Et comme l'historique complet est lui aussi disponible, vous pouvez remplir un tableau de bord rétroactivement ou tout exporter vers un entrepôt de données quand bon vous semble — vos données ne sont jamais enfermées.

Faites-vous envoyer les données par webhook

Interroger l'API à intervalles réguliers fonctionne, mais pour des intégrations en temps réel, c'est du gaspillage. Les webhooks inversent le modèle : au lieu que vous demandiez les données, SoilSense les envoie à un endpoint que vous contrôlez, à l'instant même où quelque chose se produit. Il en existe deux types.

Les webhooks de télémétrie livrent les nouvelles mesures des capteurs à mesure qu'elles arrivent — le bon choix pour les tableaux de bord en temps réel, l'irrigation automatisée et les alertes.

Les webhooks d'attributs se déclenchent lorsqu'un site d'observation est créé ou modifié, afin que vos propres enregistrements restent synchronisés sans que personne n'ait à ressaisir quoi que ce soit.

Vous enregistrez une seule URL de webhook dans les paramètres de l'appareil ; SoilSense y ajoute /telemetry et /attributes, si bien que vous exposez une route pour chacun. Chaque événement arrive sous forme de requête HTTP POST avec un corps JSON. Une charge utile de télémétrie porte un horodatage et un ensemble plat de valeurs :

{
  "ts": 1640995200000,
  "values": {
    "volumetricWaterContent_top": 25.5,
    "plantAvailableWater_top": 75.2,
    "irrigationStatus": "ok"
  }
}

La traiter est aussi simple que n'importe quelle autre route :

app.post("/telemetry", (req, res) => {
  const { ts, values } = req.body;
  // p. ex. enregistrer la mesure, mettre à jour un tableau de bord, déclencher l'irrigation
  saveReading(ts, values);
  res.sendStatus(200);
});

Vérifier que les webhooks sont authentiques

Comme l'endpoint d'un webhook est une URL publique, vous devez confirmer que chaque requête provient bien de SoilSense. Lorsque vous définissez un secret sur votre webhook, SoilSense signe chaque requête avec HMAC-SHA256 et envoie la signature dans un en-tête SoilSense-Signature, au format t=<unix_ms>,v1=<hex_hmac>. Il signe l'horodatage et le corps brut de la requête, reliés par un point — <t>.<rawBody> — de sorte que vous recalculez le même HMAC de votre côté et le comparez :

import crypto from "node:crypto";

// SoilSense-Signature: t=<unix_ms>,v1=<hex_hmac>
function isFromSoilSense(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("=")),
  );

  // SoilSense signe l'horodatage et le corps brut, reliés par un point.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  const received = Buffer.from(parts.v1, "hex");
  const computed = Buffer.from(expected, "hex");
  return (
    received.length === computed.length &&
    crypto.timingSafeEqual(received, computed)
  );
}

Deux détails comptent. Vérifiez par rapport au corps brut de la requête — les octets exacts envoyés par SoilSense, avant qu'un analyseur JSON ne les re-sérialise — sinon les empreintes ne correspondront pas. Et utilisez une comparaison à temps constant (comme ci-dessus), pour que la vérification elle-même ne divulgue aucune information. Pour une sécurité accrue contre les rejeux, rejetez toute requête dont l'horodatage t date de plus de quelques minutes.

Ce que vous pouvez construire

Un peu de code de liaison relie les données d'humidité du sol au reste de votre exploitation :

• Logiciel de gestion agricole — faites remonter l'humidité du sol et l'eau disponible pour les plantes dans la plateforme où vous planifiez déjà l'irrigation.
• Irrigation automatisée — démarrez, arrêtez ou affinez les contrôleurs à partir des mesures en temps réel et des alertes d'assèchement.
• BI et reporting — alimentez tableaux de bord, feuilles de calcul et rapports pour la comptabilité de l'eau et la conformité.
• Alertes personnalisées — acheminez les mesures vers votre propre chaîne de notification, d'automatisation ou d'analyse.

Sécurité et limites de débit

Une courte liste de contrôle avant de mettre une intégration en production :

• Gardez votre clé API côté serveur et hors du contrôle de version.
• Vérifiez les signatures des webhooks avec HMAC-SHA256 et rejetez tout ce qui échoue.
• L'API applique des limites de débit par clé — 20 requêtes par seconde, 600 par minute et 10 000 par heure, appliquées conjointement. Chaque réponse inclut les en-têtes RateLimit-Remaining et RateLimit-Reset, et un dépassement renvoie un 429. Regroupez les extractions d'historique par lots et appuyez-vous sur les webhooks pour tout ce qui doit être en temps réel.

Commencez à construire

Les données ouvertes font toute la différence entre un capteur que vous consultez une fois par jour et un système qui alimente discrètement les outils sur lesquels vous comptez déjà. Si vous voulez connecter SoilSense à votre propre stack, tout ce dont vous avez besoin est prêt :

• Lisez la vue d'ensemble complète de l'API et des webhooks
• Plongez dans la référence de l'API et les exemples

Vous avez une intégration précise en tête ? Contactez-nous — nous serons ravis de vous aider à tirer le meilleur parti de l'API et des webhooks.