Conexión por HTTP

HTTP es la forma más sencilla de conectar un dispositivo a CORE-M. Un dispositivo que pueda hacer una petición POST autenticada puede enviar telemetry — sin broker, sin conexión persistente, sin biblioteca cliente especial. Cualquier otro protocolo de esta sección termina normalizándose al mismo TelemetryPoint interno que el endpoint HTTP acepta directamente.

Endpoint


Método y ruta	`POST /api/v1/telemetry`
Puerto	`8080` (REST, servido por el gateway)
Content-Type	`application/json`
Auth	`Authorization: Bearer sk_live_...` o `X-API-Key: sk_live_...`

El endpoint está fronteado por el gateway de CORE-M, que autentica la petición, aplica el límite de tasa por tenant y la reenvía al servicio de telemetry. El tenant se deriva de la credencial — nunca colocas el tenant_id en un lugar donde un cliente pueda falsificarlo.

Autenticación

Presenta la API key de tu dispositivo en cada petición, usando cualquiera de las dos cabeceras:

Authorization: Bearer sk_live_8f3c2a...

X-API-Key: sk_live_8f3c2a...

Una petición sin credencial válida se rechaza con 401 y el payload no se publica. No incrustes la clave en URLs ni en logs.

Cuerpo de la petición — el TelemetryPoint

El cuerpo es un TelemetryPoint (o un lote de ellos — ver Ingesta por lotes). Un punto individual tiene esta forma:

{
  "device_id": "d7b1c0e2-3f44-4a91-9b2e-2c5a1f0e9d33",
  "tenant_id": "t_acme",
  "timestamp": "2026-05-29T14:03:00Z",
  "numeric_values": {
    "temperature": 22.5,
    "humidity": 65
  },
  "string_values": {
    "firmware": "1.4.2",
    "state": "running"
  }
}

Campo	Tipo	Notas
`device_id`	string	El UUID del dispositivo asignado por la plataforma.
`tenant_id`	string	El tenant propietario. Debe coincidir con el tenant de la credencial.
`timestamp`	string (RFC 3339)	Momento en que se tomó la lectura. Omítelo para que el servidor lo selle a la llegada.
`numeric_values`	map<string, double>	Lecturas de sensores en coma flotante, indexadas por nombre de métrica.
`string_values`	map<string, string>	Lecturas de tipo string (texto de estado, modos, versiones).

Un ejemplo completo

Construye el cuerpo JSON para una lectura.

Haz el POST con tu API key.

curl -X POST https://ingest.kronoxdata.com:8080/api/v1/telemetry \
  -H "Authorization: Bearer sk_live_8f3c2a..." \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "d7b1c0e2-3f44-4a91-9b2e-2c5a1f0e9d33",
    "tenant_id": "t_acme",
    "timestamp": "2026-05-29T14:03:00Z",
    "numeric_values": { "temperature": 22.5, "humidity": 65 },
    "string_values": { "state": "running" }
  }'

En caso de éxito el endpoint devuelve 200 con un acuse de ingesta que cuenta cuántos puntos aceptó:
```
{
  "accepted": 1,
  "rejected": 0
}
```

El acuse es por punto, no por petición: en un lote, los puntos malformados o de dispositivo desconocido incrementan rejected mientras que el resto se acepta igualmente.

Ingesta por lotes

Para amortizar la sobrecarga de conexión y autenticación, envía muchos puntos en una sola petición. El cuerpo del lote envuelve los puntos en un array points:

{
  "points": [
    {
      "device_id": "d7b1c0e2-...",
      "tenant_id": "t_acme",
      "timestamp": "2026-05-29T14:03:00Z",
      "numeric_values": { "temperature": 22.5 }
    },
    {
      "device_id": "d7b1c0e2-...",
      "tenant_id": "t_acme",
      "timestamp": "2026-05-29T14:03:10Z",
      "numeric_values": { "temperature": 22.7 }
    }
  ]
}

curl -X POST https://ingest.kronoxdata.com:8080/api/v1/telemetry \
  -H "Authorization: Bearer sk_live_8f3c2a..." \
  -H "Content-Type: application/json" \
  --data-binary @batch.json

La respuesta usa la misma forma { "accepted": N, "rejected": M }, sumada sobre el lote.

Downlinks por Server-Sent Events

La ingesta HTTP es unidireccional. Para mensajes servidor→dispositivo (envíos de atributos compartidos, peticiones RPC, entrega de comandos), un dispositivo abre un flujo de larga duración de Server-Sent Events y lee los downlinks a medida que llegan. Cada evento es una sola línea data: que transporta un downlink codificado en JSON, terminada por una línea en blanco según la especificación SSE:

data: {"kind":"rpc","correlation_id":"c-91a2","method":"reboot","params":{}}

data: {"kind":"shared_attributes","attributes":{"reporting_interval":30}}

El dispositivo mantiene el flujo abierto y reacciona a cada evento; si no hay ningún flujo conectado, los downlinks se encolan hasta que lo haya. Las respuestas (por ejemplo, una respuesta RPC) se envían de vuelta como uplinks autenticados normales.

Cómo fluye una ingesta HTTP

sequenceDiagram
    participant Dev as Dispositivo
    participant GW as Gateway :8080
    participant Tel as Servicio de telemetry
    participant RP as Redpanda telemetry.raw.{tenant}

    Dev->>GW: POST /api/v1/telemetry (Bearer key, JSON)
    GW->>GW: Autenticar + límite de tasa
    alt credencial inválida
        GW-->>Dev: 401 (payload no publicado)
    else autenticado
        GW->>Tel: IngestTelemetry(points)
        Tel->>Tel: Normalizar a TelemetryPoint(s)
        Tel->>RP: Publicar puntos aceptados
        Tel-->>GW: { accepted, rejected }
        GW-->>Dev: 200 { accepted, rejected }
    end

Una vez que aterriza el primer punto, el dispositivo pasa a online. Si deja de enviar durante más tiempo que el umbral de inactividad (120 segundos por defecto), se marca de nuevo como offline.

Cuándo elegir HTTP

Recurre a HTTP cuando…

El dispositivo tiene una pila TCP/TLS normal y un cliente HTTP.
La telemetry es periódica (cada pocos segundos o más lenta), no un flujo de alta frecuencia.
Quieres la menor cantidad posible de piezas móviles — sin broker, sin DTLS, sin sesión.
Estás haciendo un prototipo o integrando desde un backend, un script o una función serverless.

Si necesitas sesiones persistentes, push del servidor a escala o QoS, mira MQTT. Para dispositivos limitados en batería y ancho de banda sobre UDP, ver CoAP.

Relacionado

Envío de telemetry El modelo TelemetryPoint y el ciclo de vida de la ingesta en profundidad.

Conexión por MQTT Sesiones de broker persistentes, topics y downlinks.