Sådan integrerer du SoilSense-jordfugtighedsdata med vores API og webhooks

De fleste jordfugtighedssystemer er et lukket system: dine data kommer ind, men at få dem ud igen til dine egne værktøjer er en eftertanke. SoilSense ser det modsat. SoilSense giver dig en brugervenlig REST API og webhooks i realtid, så dine jordfugtighedsdata kan flyde ind i ethvert system, du allerede kører — landbrugsstyringssoftware, BI-dashboards, vandingscomputere eller et simpelt regneark.

Denne guide viser, hvordan du forbinder SoilSense med dine egne systemer, med praktiske eksempler både på at hente data efter behov og på at få dem sendt til dig, i samme øjeblik de ankommer.

Hvad du kan tilgå

Når dine data er åbne, bliver de målinger, dine sensorer indsamler, til byggeklodser, du kan bruge overalt. Gennem API'et kan du læse:

• Volumetrisk vandindhold (jordfugtighed) på hver sensordybde
• Jordtemperatur og salinitet
• Plantetilgængeligt vand (PAW) — det tal, der reelt fortæller dig, hvornår du skal vande
• Nedbør fra tilsluttede regnmålere
• Din bedrift og dine observationssteder, deres opsætning og hele målehistorikken
• Den seneste måling for ethvert sted, til statustjek i realtid

Det er de samme data, du ser i SoilSense-dashboardet, tilgængelige programmatisk.

Trin 1: opret en API-nøgle

API'et bruger simpel API-nøgle-godkendelse. Opret en nøgle i indstillingerne for din SoilSense-konto, og behandl den som en adgangskode — hold den hemmelig og uden for klientkode og offentlige repositories.

Hver forespørgsel bærer nøglen i en x-api-key-header. Det er hele godkendelsen: ingen OAuth-dans, ingen tokens der skal fornyes.

Trin 2: din første forespørgsel

Med en nøgle i hånden er en forespørgsel en enkelt linje. Her er den med curl, hvor du henter oplysninger om din bedrift:

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

Det samme kald fra 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);

Alle endpoints følger præcis denne form — kun stien ændrer sig. GET /api/farm/sites viser dine observationssteder og deres ID'er; derfra returnerer GET /api/site/{siteId}/observations/latest den nyeste måling, /observations hele historikken og /precipitation data fra tilsluttede regnmålere. API-referencen dokumenterer hvert endpoint med dets præcise parametre.

Trin 3: arbejd med dataene

Svarene kommer tilbage som ren JSON, så du kan sætte dem direkte ind i det, du er ved at bygge. Et svar med den seneste måling ser cirka sådan ud:

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

Målingerne er grupperet efter sensordybde (top, mid, midBot, bot), med timestamp i millisekunder siden epoch og fugtighedsværdier i procent. Herfra er det almindelig kode. Tilføj rækken til en database, send den til en Slack-kanal, når PAW falder under en tærskel, skriv den til et Google Sheet, eller videresend den til din vandingscomputer. Og fordi hele historikken også er tilgængelig, kan du efterfylde et dashboard bagud eller eksportere det hele til et data warehouse, når du vil — dine data er aldrig låst inde.

Få data sendt til dig med webhooks

At spørge API'et på et fast interval virker, men til realtidsintegrationer er det spild. Webhooks vender modellen om: i stedet for at du beder om data, sender SoilSense dem til et endpoint, du styrer, i samme øjeblik der sker noget. Der findes to slags.

Telemetri-webhooks leverer nye sensormålinger, efterhånden som de ankommer — det rigtige valg til dashboards i realtid, automatisk vanding og alarmering.

Attribut-webhooks udløses, når et observationssted oprettes eller ændres, så dine egne registreringer holdes synkroniseret, uden at nogen skal taste noget ind igen.

Du registrerer én webhook-URL i enhedsindstillingerne; SoilSense tilføjer /telemetry og /attributes, så du eksponerer én rute for hver. Hver hændelse ankommer som en HTTP POST med en JSON-body. En telemetri-payload bærer et tidsstempel og et fladt sæt værdier:

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

At håndtere den er lige så enkelt som enhver anden rute:

app.post("/telemetry", (req, res) => {
  const { ts, values } = req.body;
  // f.eks. gem målingen, opdatér et dashboard, udløs vanding
  saveReading(ts, values);
  res.sendStatus(200);
});

Bekræft at webhooks er ægte

Fordi et webhook-endpoint er en offentlig URL, bør du bekræfte, at hver forespørgsel virkelig kom fra SoilSense. Når du sætter en hemmelighed på dit webhook, signerer SoilSense hver forespørgsel med HMAC-SHA256 og sender signaturen i en SoilSense-Signature-header i formatet t=<unix_ms>,v1=<hex_hmac>. Den signerer tidsstemplet og den rå body samlet med et punktum — <t>.<rawBody> — så du kan genberegne den samme HMAC på din side og sammenligne:

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 signerer tidsstemplet og den rå body, samlet med et punktum.
  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)
  );
}

To detaljer er vigtige. Bekræft mod den rå forespørgselsbody — de præcise bytes, SoilSense sendte, før en JSON-parser genserialiserer dem — ellers vil hashene ikke stemme. Og brug en sammenligning i konstant tid (som ovenfor), så selve tjekket ikke lækker information. For ekstra sikkerhed mod replay bør du afvise enhver forespørgsel, hvis t-tidsstempel er mere end et par minutter gammelt.

Hvad du kan bygge

Lidt limkode forbinder jordfugtighedsdata med resten af din drift:

• Landbrugsstyringssoftware — bring jordfugtighed og plantetilgængeligt vand ind i den platform, hvor du allerede planlægger vanding.
• Automatisk vanding — start, stop eller finjustér computere ud fra målinger i realtid og udtørringsalarmer.
• BI og rapportering — fød dashboards, regneark og rapporter til vandregnskab og compliance.
• Egne alarmer — dirigér målinger ind i din egen pipeline til notifikationer, automatisering eller analyse.

Sikkerhed og hastighedsgrænser

En hurtig tjekliste, før du sender en integration i produktion:

• Hold din API-nøgle på serversiden og uden for versionsstyring.
• Bekræft webhook-signaturer med HMAC-SHA256, og afvis alt, der ikke består tjekket.
• API'et anvender hastighedsgrænser pr. nøgle — 20 forespørgsler i sekundet, 600 i minuttet og 10.000 i timen, håndhævet samlet. Hvert svar indeholder headerne RateLimit-Remaining og RateLimit-Reset, og overskrider du dem, får du et 429. Saml historiske træk i batches, og læn dig op ad webhooks til alt, der skal være i realtid.

Kom i gang

Åbne data er forskellen mellem en sensor, du læser én gang om dagen, og et system, der stille driver de værktøjer, du allerede er afhængig af. Hvis du vil forbinde SoilSense med din egen stak, er alt det, du skal bruge, klar:

• Læs den fulde oversigt over API og webhooks
• Dyk ned i API-referencen og eksemplerne

Har du en bestemt integration i tankerne? Kontakt os — vi hjælper dig gerne med at få mest muligt ud af API'et og webhooks.