Jak zintegrować dane o wilgotności gleby SoilSense przez nasze API i webhooki

Większość systemów czujników wilgotności gleby to zamknięty system: Twoje dane wchodzą do środka, ale wyciągnięcie ich z powrotem do własnych narzędzi to już kwestia drugorzędna. SoilSense patrzy na to odwrotnie. SoilSense udostępnia proste w użyciu API REST i webhooki na żywo, więc Twoje dane o wilgotności gleby mogą trafić do każdego systemu, którego już używasz — oprogramowania do zarządzania gospodarstwem, paneli BI, sterowników nawadniania czy zwykłego arkusza kalkulacyjnego.

Ten przewodnik pokazuje, jak połączyć SoilSense z własnymi systemami, z praktycznymi przykładami zarówno pobierania danych na żądanie, jak i otrzymywania ich w chwili, gdy się pojawią.

Do czego masz dostęp

Gdy Twoje dane są otwarte, odczyty zbierane przez czujniki stają się klockami, których możesz użyć wszędzie. Przez API możesz odczytać:

• Objętościową zawartość wody (wilgotność gleby) na każdej głębokości czujnika
• Temperaturę gleby i zasolenie
• Wodę dostępną dla roślin (PAW) — wskaźnik, który naprawdę mówi Ci, kiedy nawadniać
• Opady z podłączonych deszczomierzy
• Twoje gospodarstwo i lokalizacje pomiarowe, ich konfigurację oraz pełną historię pomiarów
• Najnowszy odczyt z dowolnej lokalizacji, do sprawdzania stanu na żywo

To te same dane, które widzisz w panelu SoilSense, dostępne programowo.

Krok 1: utwórz klucz API

API korzysta z prostego uwierzytelniania kluczem API. Utwórz klucz w ustawieniach swojego konta SoilSense i traktuj go jak hasło — trzymaj go w tajemnicy, poza kodem po stronie klienta i publicznymi repozytoriami.

Każde zapytanie niesie klucz w nagłówku x-api-key. To całe uwierzytelnianie: żadnych tańców z OAuth, żadnych tokenów do odświeżania.

Krok 2: pierwsze zapytanie

Z kluczem w ręku zapytanie to pojedyncza linia. Oto ono w curl, pobierające dane Twojego gospodarstwa:

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

To samo wywołanie z JavaScriptu:

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);

Każdy endpoint ma dokładnie ten sam kształt — zmienia się tylko ścieżka. GET /api/farm/sites zwraca listę Twoich lokalizacji pomiarowych i ich identyfikatory; stamtąd GET /api/site/{siteId}/observations/latest zwraca najnowszy odczyt, /observations pełną historię, a /precipitation dane z podłączonych deszczomierzy. Dokumentacja API opisuje każdy endpoint wraz z dokładnymi parametrami.

Krok 3: pracuj z danymi

Odpowiedzi wracają jako czysty JSON, więc możesz wstawić je wprost do tego, co budujesz. Odpowiedź z najnowszym odczytem wygląda mniej więcej tak:

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

Odczyty są pogrupowane według głębokości czujnika (top, mid, midBot, bot), z timestamp w milisekundach od epoki i wartościami wilgotności w procentach. Dalej to już zwykły kod. Dopisz wiersz do bazy danych, wyślij go na kanał Slack, gdy PAW spadnie poniżej progu, zapisz w Arkuszu Google albo przekaż do sterownika nawadniania. A ponieważ dostępna jest też pełna historia, możesz uzupełnić panel wstecz albo wyeksportować wszystko do hurtowni danych, kiedy tylko chcesz — Twoje dane nigdy nie są zamknięte.

Odbieraj dane przez webhooki

Odpytywanie API w stałych odstępach działa, ale przy integracjach na żywo to marnotrawstwo. Webhooki odwracają model: zamiast tego, że to Ty prosisz o dane, SoilSense sam wysyła je na kontrolowany przez Ciebie endpoint w chwili, gdy coś się wydarzy. Są dwa rodzaje.

Webhooki telemetryczne dostarczają nowe odczyty czujników w miarę ich napływania — właściwy wybór do paneli na żywo, automatycznego nawadniania i powiadomień.

Webhooki atrybutów uruchamiają się, gdy lokalizacja pomiarowa zostaje utworzona lub zmieniona, dzięki czemu Twoje własne rejestry pozostają zsynchronizowane, a nikt nie musi niczego przepisywać ręcznie.

Rejestrujesz jeden adres URL webhooka w ustawieniach urządzenia; SoilSense dokleja do niego /telemetry i /attributes, więc udostępniasz po jednej trasie dla każdego. Każde zdarzenie przychodzi jako żądanie HTTP POST z treścią JSON. Ładunek telemetryczny niesie znacznik czasu i płaski zestaw wartości:

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

Obsługa jest tak prosta jak każdej innej trasy:

app.post("/telemetry", (req, res) => {
  const { ts, values } = req.body;
  // np. zapisz odczyt, zaktualizuj panel, uruchom nawadnianie
  saveReading(ts, values);
  res.sendStatus(200);
});

Sprawdź, czy webhooki są autentyczne

Ponieważ endpoint webhooka to publiczny adres URL, warto potwierdzić, że każde żądanie naprawdę pochodzi z SoilSense. Gdy ustawisz sekret dla swojego webhooka, SoilSense podpisuje każde żądanie za pomocą HMAC-SHA256 i wysyła podpis w nagłówku SoilSense-Signature, w formacie t=<unix_ms>,v1=<hex_hmac>. Podpisuje znacznik czasu i surową treść żądania połączone kropką — <t>.<rawBody> — więc przeliczasz ten sam HMAC po swojej stronie i porównujesz:

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 podpisuje znacznik czasu i surowe body połączone kropką.
  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)
  );
}

Ważne są dwa szczegóły. Weryfikuj względem surowej treści żądania — dokładnych bajtów wysłanych przez SoilSense, zanim parser JSON zserializuje je na nowo — bo inaczej skróty się nie zgodzą. I stosuj porównanie o stałym czasie (jak wyżej), aby sama weryfikacja nie ujawniała informacji. Dla dodatkowego zabezpieczenia przed powtórzeniami odrzucaj każde żądanie, którego znacznik t jest starszy niż kilka minut.

Co możesz zbudować

Odrobina kodu spinającego łączy dane o wilgotności gleby z resztą Twojej działalności:

• Oprogramowanie do zarządzania gospodarstwem — wprowadź wilgotność gleby i wodę dostępną dla roślin do platformy, w której i tak planujesz nawadnianie.
• Automatyczne nawadnianie — uruchamiaj, zatrzymuj lub dostrajaj sterowniki na podstawie odczytów na żywo i powiadomień o przesychaniu.
• BI i raportowanie — zasilaj panele, arkusze i raporty na potrzeby rozliczania wody i zgodności z przepisami.
• Własne powiadomienia — kieruj odczyty do własnego potoku powiadomień, automatyzacji lub analityki.

Bezpieczeństwo i limity zapytań

Krótka lista kontrolna, zanim wdrożysz integrację:

• Trzymaj klucz API po stronie serwera i poza systemem kontroli wersji.
• Weryfikuj podpisy webhooków za pomocą HMAC-SHA256 i odrzucaj wszystko, co nie przejdzie kontroli.
• API stosuje limity zapytań na klucz — 20 zapytań na sekundę, 600 na minutę i 10 000 na godzinę, egzekwowane łącznie. Każda odpowiedź zawiera nagłówki RateLimit-Remaining i RateLimit-Reset, a przekroczenie limitu zwraca 429. Grupuj pobieranie historii w partie i opieraj się na webhookach przy wszystkim, co musi działać na żywo.

Zacznij budować

Otwarte dane to różnica między czujnikiem, który sprawdzasz raz dziennie, a systemem, który po cichu napędza narzędzia, na których już polegasz. Jeśli chcesz połączyć SoilSense z własnym stosem technologicznym, masz już wszystko, czego potrzebujesz:

• Przeczytaj pełny przegląd API i webhooków
• Zajrzyj do dokumentacji API z przykładami

Masz na myśli konkretną integrację? Skontaktuj się z nami — chętnie pomożemy Ci wycisnąć z API i webhooków jak najwięcej.