Come integrare i dati di umidità del suolo di SoilSense con la nostra API e i webhook

La maggior parte dei sistemi di sensori per l'umidità del suolo è un sistema chiuso: i tuoi dati entrano, ma tirarli fuori per i tuoi strumenti è un ripensamento. SoilSense la vede all'opposto. SoilSense offre un'API REST facile da usare e webhook in tempo reale, così i tuoi dati di umidità del suolo possono confluire in qualsiasi sistema che già utilizzi — software di gestione agricola, dashboard di BI, centraline di irrigazione o un semplice foglio di calcolo.

Questa guida mostra come collegare SoilSense ai tuoi sistemi, con esempi pratici sia per richiedere i dati quando ti servono sia per riceverli non appena arrivano.

Cosa puoi consultare

Con i tuoi dati aperti, le letture raccolte dai sensori diventano mattoni che puoi usare ovunque. Tramite l'API puoi leggere:

• Contenuto idrico volumetrico (umidità del suolo) a ogni profondità del sensore
• Temperatura del suolo e salinità
• Acqua disponibile per le piante (PAW) — il dato che ti dice davvero quando irrigare
• Precipitazioni dai pluviometri collegati
• La tua azienda e i tuoi siti di osservazione, la loro configurazione e l'intero storico delle misurazioni
• L'ultima lettura di qualsiasi sito, per controlli di stato in tempo reale

Sono gli stessi dati che vedi nella dashboard di SoilSense, disponibili in modo programmatico.

Passo 1: crea una chiave API

L'API usa una semplice autenticazione con chiave API. Crea una chiave nelle impostazioni del tuo account SoilSense e trattala come una password — tienila segreta e fuori dal codice lato client e dai repository pubblici.

Ogni richiesta porta la chiave in un header x-api-key. È tutta qui l'autenticazione: niente giri con OAuth, nessun token da rinnovare.

Passo 2: la tua prima richiesta

Con la chiave in mano, una richiesta è una sola riga. Eccola con curl, per leggere i dati della tua azienda:

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

La stessa chiamata da 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);

Ogni endpoint segue esattamente questa forma — cambia solo il percorso. GET /api/farm/sites elenca i tuoi siti di osservazione e i loro ID; da lì, GET /api/site/{siteId}/observations/latest restituisce l'ultima lettura, /observations l'intero storico e /precipitation i dati dei pluviometri collegati. La documentazione dell'API descrive ogni endpoint con i suoi parametri esatti.

Passo 3: lavora con i dati

Le risposte arrivano come JSON pulito, quindi puoi inserirle direttamente in ciò che stai costruendo. Una risposta con l'ultima lettura ha più o meno questo aspetto:

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

Le letture sono raggruppate per profondità del sensore (top, mid, midBot, bot), con timestamp in millisecondi dall'epoch e i valori di umidità in percentuale. Da qui è codice ordinario. Aggiungi la riga a un database, pubblicala su un canale Slack quando la PAW scende sotto una soglia, scrivila in un foglio di Google o inoltrala alla tua centralina di irrigazione. E poiché è disponibile anche l'intero storico, puoi popolare a ritroso una dashboard o esportare tutto in un data warehouse quando vuoi — i tuoi dati non restano mai bloccati.

Ricevi i dati con i webhook

Interrogare l'API a intervalli regolari funziona, ma per le integrazioni in tempo reale è uno spreco. I webhook ribaltano il modello: invece di essere tu a chiedere i dati, è SoilSense a inviarli a un endpoint che controlli tu, nel momento stesso in cui qualcosa accade. Ne esistono due tipi.

I webhook di telemetria consegnano le nuove letture dei sensori man mano che arrivano — la scelta giusta per dashboard in tempo reale, irrigazione automatica e avvisi.

I webhook degli attributi scattano quando un sito di osservazione viene creato o modificato, così i tuoi archivi restano allineati senza che nessuno debba reinserire nulla a mano.

Registri un unico URL per i webhook nelle impostazioni del dispositivo; SoilSense vi aggiunge /telemetry e /attributes, quindi esponi una rotta per ciascuno. Ogni evento arriva come una richiesta HTTP POST con un corpo JSON. Un payload di telemetria porta un timestamp e un insieme piatto di valori:

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

Gestirlo è semplice come qualsiasi altra rotta:

app.post("/telemetry", (req, res) => {
  const { ts, values } = req.body;
  // es. salva la lettura, aggiorna una dashboard, avvia l'irrigazione
  saveReading(ts, values);
  res.sendStatus(200);
});

Verificare che i webhook siano autentici

Poiché l'endpoint di un webhook è un URL pubblico, dovresti confermare che ogni richiesta provenga davvero da SoilSense. Quando imposti un segreto sul tuo webhook, SoilSense firma ogni richiesta con HMAC-SHA256 e invia la firma in un header SoilSense-Signature, nel formato t=<unix_ms>,v1=<hex_hmac>. Firma il timestamp e il corpo grezzo della richiesta uniti da un punto — <t>.<rawBody> — così puoi ricalcolare lo stesso HMAC dalla tua parte e confrontarlo:

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 firma il timestamp e il corpo grezzo, uniti da un punto.
  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)
  );
}

Due dettagli sono importanti. Verifica rispetto al corpo grezzo della richiesta — i byte esatti inviati da SoilSense, prima che un parser JSON li ri-serializzi — altrimenti gli hash non coincideranno. E usa un confronto a tempo costante (come sopra), così il controllo stesso non lascia trapelare informazioni. Per una sicurezza extra contro i replay, rifiuta ogni richiesta il cui timestamp t sia più vecchio di qualche minuto.

Cosa puoi costruire

Basta un po' di codice di collegamento per portare i dati di umidità del suolo nel resto della tua attività:

• Software di gestione agricola — porta umidità del suolo e acqua disponibile per le piante nella piattaforma dove già pianifichi l'irrigazione.
• Irrigazione automatica — avvia, ferma o regola le centraline in base alle letture in tempo reale e agli avvisi di asciugatura.
• BI e reportistica — alimenta dashboard, fogli di calcolo e report per la contabilità dell'acqua e la conformità.
• Avvisi personalizzati — instrada le letture nella tua pipeline di notifiche, automazione o analisi.

Sicurezza e limiti di frequenza

Una rapida lista di controllo prima di mettere in produzione un'integrazione:

• Tieni la chiave API lato server e fuori dal controllo di versione.
• Verifica le firme dei webhook con HMAC-SHA256 e rifiuta tutto ciò che non passa il controllo.
• L'API applica limiti di frequenza per chiave — 20 richieste al secondo, 600 al minuto e 10.000 all'ora, applicati insieme. Ogni risposta include gli header RateLimit-Remaining e RateLimit-Reset, e superare i limiti restituisce un 429. Raggruppa le letture storiche in batch e affidati ai webhook per tutto ciò che deve essere in tempo reale.

Inizia a costruire

I dati aperti sono la differenza tra un sensore che leggi una volta al giorno e un sistema che alimenta silenziosamente gli strumenti su cui già fai affidamento. Se vuoi collegare SoilSense al tuo stack, hai già tutto il necessario:

• Leggi la panoramica completa su API e webhook
• Approfondisci la documentazione dell'API con gli esempi

Hai in mente un'integrazione specifica? Contattaci — siamo felici di aiutarti a sfruttare al meglio l'API e i webhook.