Una API clara para conectar dispositivos, leer sensores y automatizar operaciones.

La plataforma esta pensada para crecer con tu operacion.

X Grow Labs no depende de una sola placa, una sola marca ni un solo paquete de sensores. La arquitectura separa identidad del dispositivo, perfil de capacidades, muestras de sensores, comandos pendientes y automatizacion. Gracias a eso, la misma web puede recibir nodos sencillos de temperatura y humedad, estaciones multipunto, controladores de reles o equipos mas especializados, todo dentro de un mismo flujo de trabajo.

Como puede comunicarse un dispositivo con la plataforma

Para integrarse, un equipo no tiene que pertenecer a una marca especifica. Solo necesita cumplir un contrato sencillo: identificarse con un token propio, enviar peticiones HTTPS, hablar JSON y reportar sus mediciones con llaves de sensor coherentes con su perfil. A partir de ahi, la web puede incorporarlo al flujo completo de datos y automatizacion.

Flujo completo entre hardware, API, dashboard y automatizacion

Este es el recorrido real dentro de la web, desde que se crea un dispositivo hasta que sus datos se convierten en informacion visible y acciones automatizadas.

Escalabilidad, apertura y evolucion del sistema

La plataforma fue organizada para que el crecimiento no dependa de reescribir la operacion central cada vez que entra un nuevo nodo. El escalado se resuelve por separacion de tenant, perfiles de dispositivo, llaves de sensor, lotes de telemetria y consultas controladas de actuadores.

Referencia activa de endpoints

Los siguientes endpoints forman la superficie operativa actual para nodos de telemetria, control de salidas y tareas de automatizacion. Los ejemplos estan listos para copiar, adaptar e integrar con rapidez.

{
  "metrics": {
    "temperature": 25.3,
    "humidity": 58.1
  },
  "at": "2026-05-27T12:00:00Z",
  "firmware_version": "esp01_th_v1-1.4.2"
}

{
  "ok": true,
  "message": "Telemetria registrada.",
  "data": {
    "inserted": 2,
    "device_id": 17
  }
}

{
  "at": "2026-05-27T12:00:00Z",
  "firmware_version": "esp32_soil6_env_v1-0.9.0",
  "samples": [
    { "key": "air_temperature", "value": 24.8 },
    { "key": "air_humidity", "value": 56.4 },
    { "key": "soil_1", "value": 41 },
    { "key": "soil_2", "value": 39 }
  ]
}

{
  "ok": true,
  "message": "Muestras registradas.",
  "data": {
    "inserted": 4,
    "device_id": 24
  }
}

curl -X GET "https://dashboard.xgrowlabs.com/api/v1/relays/state" \
  -H "X-Device-Token: YOUR_DEVICE_TOKEN"

{
  "ok": true,
  "message": "OK",
  "data": {
    "device": {
      "id": 12,
      "hardware_uid": "esp01-4relay-lab-a"
    },
    "relays": {
      "1": 1,
      "2": 0,
      "3": 0,
      "4": 1
    }
  }
}

{
  "relays": {
    "1": 1,
    "2": 0,
    "3": 0,
    "4": 1
  }
}

{
  "ok": true,
  "message": "Reles actualizados.",
  "data": {
    "device": {
      "id": 12,
      "hardware_uid": "esp01-4relay-lab-a"
    }
  }
}

curl -X GET "https://dashboard.xgrowlabs.com/api/v1/cron/relays?token=YOUR_CRON_TOKEN"

{
  "ok": true,
  "message": "OK",
  "data": {
    "runs": [
      {
        "tenant_id": 3,
        "name": "Cultivo Norte",
        "result": {},
        "grow_plan_result": {}
      }
    ]
  }
}

curl -X GET "https://dashboard.xgrowlabs.com/api/v1/cron/relays/tenant/3?token=YOUR_CRON_TOKEN"

{
  "ok": true,
  "message": "OK",
  "data": {
    "tenant_id": 3,
    "tenant": "Cultivo Norte",
    "result": {},
    "grow_plan_result": {}
  }
}

Ejemplos por tipo de integracion

Estos ejemplos muestran la idea general para distintos tipos de cliente. El objetivo es que cualquier equipo, desde un microcontrolador hasta un servicio intermedio, pueda entender como entrar al flujo de X Grow Labs.

POST /api/v1/telemetry/samples
Headers:
  Content-Type: application/json
  X-Device-Token: YOUR_DEVICE_TOKEN

Body:
{
  "firmware_version": "esp32-grow-node-v1",
  "samples": [
    { "key": "air_temperature", "value": 24.8 },
    { "key": "air_humidity", "value": 56.4 },
    { "key": "light_lux", "value": 18450 }
  ]
}

Flujo sugerido:
1. Leer sensores locales o equipos por serial, Modbus o GPIO
2. Transformar lecturas a llaves compatibles
3. Enviar batches periodicos a /telemetry o /telemetry/samples
4. Consultar /relays/state si tambien controla salidas

Responsabilidades del integrador:
- Recibir lecturas del hardware
- Mapear nombres internos a llaves compatibles
- Validar rangos y tipos numericos
- Enviar payloads HTTPS a la API
- Consultar reles y devolver ack cuando aplique

Sensores, actuadores y capacidades que la web puede modelar

Hoy la plataforma ya contempla familias comunes para monitoreo de cultivo y control. Eso incluye temperatura, humedad, luz, humedad de suelo, CO2, pH, EC y nivel de agua, ademas de salidas como reles y displays. En terminos de producto, esto significa que la web puede representar nodos simples, nodos de ambiente, controladores de salidas y estaciones mas completas con varias entradas simultaneas.

Errores comunes y como evitarlos

En integraciones IoT, los problemas mas frecuentes no suelen venir del transporte, sino de desalineacion entre llaves de sensor, perfiles provisionados, autenticacion o frecuencia de polling.

• 401 Unauthorized: falta X-Device-Token, el token no existe o el firmware envia un formato invalido.
• 422 Unprocessable Entity: el payload es valido como JSON, pero no coincide con la estructura o las capacidades esperadas por el dispositivo.
• 400 Bad Request: falta metrics, readings o samples, o el dispositivo no quedo bien vinculado a tenant.
• 403 Forbidden: el token de cron no coincide y la automatizacion queda bloqueada por seguridad.
• Lecturas sin impacto visual: normalmente indica que la llave reportada por el firmware no coincide con una capacidad provisionada para ese perfil.