Cómo integrar los datos de humedad del suelo de SoilSense con nuestra API y webhooks

La mayoría de los sistemas de sensores de humedad del suelo son un sistema cerrado: tus datos entran, pero recuperarlos para tus propias herramientas es una idea de última hora. SoilSense lo ve al revés. SoilSense ofrece una API REST fácil de usar y webhooks en tiempo real, para que tus datos de humedad del suelo puedan fluir a cualquier sistema que ya utilices — software de gestión agrícola, paneles de BI, controladores de riego o una simple hoja de cálculo.

Esta guía muestra cómo conectar SoilSense con tus propios sistemas, con ejemplos prácticos tanto para consultar los datos cuando los necesitas como para recibirlos en cuanto llegan.

A qué puedes acceder

Con tus datos abiertos, las lecturas que recogen tus sensores se convierten en piezas que puedes usar en cualquier parte. A través de la API puedes leer:

• Contenido volumétrico de agua (humedad del suelo) a cada profundidad del sensor
• Temperatura del suelo y salinidad
• Agua disponible para las plantas (PAW) — el dato que de verdad te dice cuándo regar
• Precipitación de los pluviómetros conectados
• Tu explotación y tus sitios de observación, su configuración y todo el historial de mediciones
• La última lectura de cualquier sitio, para comprobaciones de estado en tiempo real

Son los mismos datos que ves en el panel de SoilSense, disponibles de forma programática.

Paso 1: crea una clave API

La API usa una autenticación sencilla con clave API. Crea una clave en los ajustes de tu cuenta de SoilSense y trátala como una contraseña — mantenla en secreto y fuera del código del lado del cliente y de los repositorios públicos.

Cada solicitud lleva la clave en una cabecera x-api-key. Ahí está toda la autenticación: sin bailes con OAuth, sin tokens que renovar.

Paso 2: tu primera solicitud

Con la clave en la mano, una solicitud es una sola línea. Aquí está con curl, para leer los datos de tu explotación:

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

La misma llamada desde 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);

Cada endpoint sigue exactamente esta forma — solo cambia la ruta. GET /api/farm/sites lista tus sitios de observación y sus IDs; desde ahí, GET /api/site/{siteId}/observations/latest devuelve la lectura más reciente, /observations todo el historial y /precipitation los datos de los pluviómetros conectados. La referencia de la API documenta cada endpoint con sus parámetros exactos.

Paso 3: trabaja con los datos

Las respuestas llegan como JSON limpio, así que puedes incorporarlas directamente a lo que estés construyendo. Una respuesta con la última lectura tiene más o menos este aspecto:

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

Las lecturas se agrupan por profundidad del sensor (top, mid, midBot, bot), con timestamp en milisegundos desde el epoch y los valores de humedad en porcentaje. A partir de aquí es código corriente. Añade la fila a una base de datos, publícala en un canal de Slack cuando la PAW baje de un umbral, escríbela en una hoja de Google o reenvíala a tu controlador de riego. Y como también está disponible todo el historial, puedes rellenar un panel hacia atrás o exportarlo todo a un data warehouse cuando quieras — tus datos nunca quedan atrapados.

Recibe los datos con webhooks

Consultar la API a intervalos funciona, pero para integraciones en tiempo real es un desperdicio. Los webhooks le dan la vuelta al modelo: en lugar de que tú pidas los datos, SoilSense los envía a un endpoint que tú controlas en el momento en que ocurre algo. Hay dos tipos.

Los webhooks de telemetría entregan las nuevas lecturas de los sensores a medida que llegan — la opción adecuada para paneles en tiempo real, riego automático y alertas.

Los webhooks de atributos se disparan cuando se crea o se modifica un sitio de observación, para que tus propios registros se mantengan sincronizados sin que nadie tenga que reescribir nada a mano.

Registras una única URL de webhook en los ajustes del dispositivo; SoilSense le añade /telemetry y /attributes, así que expones una ruta para cada uno. Cada evento llega como una solicitud HTTP POST con un cuerpo JSON. Un payload de telemetría lleva una marca de tiempo y un conjunto plano de valores:

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

Manejarlo es tan sencillo como cualquier otra ruta:

app.post("/telemetry", (req, res) => {
  const { ts, values } = req.body;
  // p. ej. guarda la lectura, actualiza un panel, activa el riego
  saveReading(ts, values);
  res.sendStatus(200);
});

Verifica que los webhooks son auténticos

Como el endpoint de un webhook es una URL pública, deberías confirmar que cada solicitud viene realmente de SoilSense. Cuando estableces un secreto en tu webhook, SoilSense firma cada solicitud con HMAC-SHA256 y envía la firma en una cabecera SoilSense-Signature, con el formato t=<unix_ms>,v1=<hex_hmac>. Firma la marca de tiempo y el cuerpo en bruto de la solicitud unidos por un punto — <t>.<rawBody> — de modo que recalculas el mismo HMAC en tu lado y lo comparas:

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 la marca de tiempo y el cuerpo en bruto, unidos por 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)
  );
}

Dos detalles importan. Verifica contra el cuerpo en bruto de la solicitud — los bytes exactos que envió SoilSense, antes de que un analizador JSON los vuelva a serializar — o los hashes no coincidirán. Y usa una comparación de tiempo constante (como arriba), para que la propia comprobación no filtre información. Para mayor seguridad frente a repeticiones, rechaza cualquier solicitud cuya marca de tiempo t tenga más de unos minutos de antigüedad.

Qué puedes construir

Con un poco de código de pegamento conectas los datos de humedad del suelo con el resto de tu operación:

• Software de gestión agrícola — lleva la humedad del suelo y el agua disponible para las plantas a la plataforma donde ya planificas el riego.
• Riego automático — arranca, detén o ajusta los controladores a partir de las lecturas en tiempo real y las alertas de secado.
• BI y reporting — alimenta paneles, hojas de cálculo e informes para la contabilidad del agua y el cumplimiento normativo.
• Alertas personalizadas — encamina las lecturas hacia tu propia canalización de notificaciones, automatización o analítica.

Seguridad y límites de frecuencia

Una lista de comprobación rápida antes de poner en producción una integración:

• Mantén tu clave API en el lado del servidor y fuera del control de versiones.
• Verifica las firmas de los webhooks con HMAC-SHA256 y rechaza todo lo que no pase la comprobación.
• La API aplica límites de frecuencia por clave — 20 solicitudes por segundo, 600 por minuto y 10.000 por hora, aplicados en conjunto. Cada respuesta incluye las cabeceras RateLimit-Remaining y RateLimit-Reset, y superarlos devuelve un 429. Agrupa en lotes las descargas de histórico y apóyate en los webhooks para todo lo que deba ser en tiempo real.

Empieza a construir

Los datos abiertos son la diferencia entre un sensor que consultas una vez al día y un sistema que alimenta en silencio las herramientas de las que ya dependes. Si quieres conectar SoilSense con tu propio stack, ya tienes todo lo necesario:

• Lee la visión general completa de la API y los webhooks
• Profundiza en la referencia de la API y los ejemplos

¿Tienes en mente una integración concreta? Ponte en contacto — estaremos encantados de ayudarte a sacar el máximo partido de la API y los webhooks.