API de ingesta de telemetría

AudienciaIntegradores, Ingenieros OT/IT

Permisos requeridosLlave Telemetry API activa para la planta destino

Tiempo estimado6 min de lectura

Planta democemento-valladolid

Usa la Telemetry API (telemetry-api) para enviar lecturas de sensores en tiempo real hacia una planta en OTCognix.

Endpoint

POST /api/v1/ingest/iot-data

Autenticación

Usa HTTP Basic Authentication con tu credencial de telemetría (key como usuario, secret como contraseña). El alcance de planta y compañía se obtiene exclusivamente de la credencial autenticada, nunca del cuerpo de la petición.

Payload de la petición

Campo	Tipo	Descripción
timestamp	integer	Marca de tiempo Unix epoch en milisegundos al enviar el lote.
values	array	Lista no vacía de lecturas (id, v, q, t).
values[].id	string	Identificador Source Tag (cadena no vacía).
values[].v	number	Valor numérico de la medición.
values[].q	boolean	Bandera de calidad (true = Good, false = Bad).
values[].t	integer	Marca de tiempo del sensor (Unix epoch en milisegundos).

{
  "timestamp": 1754802764766,
  "values": [
    {
      "id": "CDEMO.CM01.CIR001.FRESH_FEED",
      "v": 60.41,
      "q": true,
      "t": 1754802759166
    }
  ]
}

Respuestas

• 201 Created: Lote aceptado y encolado en Redis Streams (incluye tags rechazados si hubiera).
• 401 Unauthorized: Credenciales faltantes, inválidas o inactivas.
• 422 Unprocessable Entity: Payload inválido o sin tags utilizables.
• 429 Too Many Requests: Límite de tasa excedido (revisar Retry-After).
• 503 Service Unavailable: Falla en servicio de credenciales o almacenamiento (Retry-After: 5).
• 500 / 504: Error inesperado o timeout aguas abajo.

Semántica de entrega

Un 201 confirma ingesta en Redis, no persistencia final en TimescaleDB. Si ocurre un 503 a mitad de lote, escrituras parciales pudieron persistirse — reintenta con semántica at-least-once.