Guía para pruebas

Guía de la API de Dynasystem para pruebas

v1.0, 20 de noviembre de 2026. Para el equipo técnico de Orange.
Esta guía describe la API de lectura de Dynasystem: cómo autenticarse con una clave, cada ruta con su llamada de ejemplo, los formatos de respuesta, los errores y los límites. Con ella, el equipo técnico puede consultar por programa los puntos de medición, los equipos, las alarmas y las series de mediciones de su cuenta.

1. Introducción

La API de Dynasystem permite consultar por programa los datos de su cuenta: los puntos de medición con sus magnitudes, los equipos, las alarmas abiertas, las series de mediciones y el registro de las tramas que han llegado a la plataforma.

La plataforma recibe los datos de equipos de terreno, entre ellos nodos satelitales NTN, y los pone a disposición en el portal web (https://app.dynasystem.cl) y en esta API. Un equipo satelital mide en terreno, guarda y entrega cuando pasa el satélite, por lo que entre la medición y su llegada pueden pasar varias horas. La API distingue ambas horas en cada dato.

Esta guía describe cada ruta, con su llamada de ejemplo, los errores posibles y los límites vigentes.

2. Cómo comenzar

Para realizar las pruebas, Dynasystem proporciona:

Con esos elementos, el recorrido básico es el siguiente:

  1. Verifique que el servicio responde: curl https://app.dynasystem.cl/api/v1/external/openapi.yaml.
  2. Liste los puntos de medición de la cuenta con /measurement-points. De ahí se obtiene el identificador de cada elemento (elementId).
  3. Consulte las tramas recibidas con /receptions.
  4. Pida los valores de un elemento con /series.
  5. Consulte los equipos con /devices y las alarmas abiertas con /alarms.

El detalle de cada ruta está en la sección 5, y un recorrido completo con ejemplos en la sección 6.

3. Conceptos básicos

4. Autenticación

La API se autentica con una clave de API. No requiere OAuth ni usuario y contraseña.

La clave:

Se envía siempre en la cabecera, nunca en la dirección:

Authorization: Bearer dsk_...

Para los ejemplos de esta guía, defina la clave y la dirección base como variables de su terminal:

export DYNA_CLAVE='dsk_...'
export DYNA_URL='https://app.dynasystem.cl/api/v1/external'

Una clave ausente, mal formada, inexistente o revocada responde 401 api-key-invalid.

5. Referencia de la API

Seis rutas, todas GET, bajo https://app.dynasystem.cl/api/v1/external. Cada una trae su ejemplo de llamada. Los valores de las respuestas son de ejemplo; la forma, los nombres y los tipos son los del contrato publicado (OpenAPI 3.1, versión 1.1.0).

Todas las rutas pueden responder 401, 403 y 429. Además, /series puede responder 400, 404 y 503, y /receptions, 400. El significado de cada error está en la sección 7.

5.1 GET /measurement-points: Los puntos de medición con sus elementos

De aquí salen los ids de elemento que pide /series.

curl -s -H "Authorization: Bearer $DYNA_CLAVE" "$DYNA_URL/measurement-points"

Respuesta 200 (valores de ejemplo):

[
  {
    "id": "310",
    "name": "Pozo norte",
    "siteId": "12",
    "siteZone": "America/Santiago",
    "elements": [
      { "id": "101", "code": "temperatura_modbus_1", "unit": "C" }
    ]
  }
]

Campos de cada elemento (tipo Punto):

CampoTipoQué es
idtextoIdentificador del punto.
nametextoNombre.
siteIdtextoEl sitio donde está el punto.
siteZonetextoLa zona horaria del sitio (por ejemplo America/Santiago).
elementslista de ElementoLas magnitudes que mide el punto (temperatura, corriente, etc.).

5.2 GET /devices: Los equipos del cliente

curl -s -H "Authorization: Bearer $DYNA_CLAVE" "$DYNA_URL/devices"

Respuesta 200 (valores de ejemplo):

[
  {
    "id": "4821",
    "identifier": "9001",
    "status": "active",
    "measurementPointId": "310",
    "measurementPointName": "Pozo norte"
  }
]

Campos de cada elemento (tipo Equipo):

CampoTipoQué es
idtextoIdentificador interno del equipo.
identifiertextoEl identificador impreso en el equipo.
statusactive o revokedEstado del equipo: activo o revocado.
measurementPointIdtexto o nuloEl punto donde está instalado, o nulo si no lo está.
measurementPointNametexto o nuloNombre del punto.

5.3 GET /alarms: Las alarmas abiertas

No incluye quién las reconoció: es una persona.

curl -s -H "Authorization: Bearer $DYNA_CLAVE" "$DYNA_URL/alarms"

Respuesta 200 (valores de ejemplo):

[
  {
    "id": "5521",
    "measurementPointId": "310",
    "measurementPointName": "Pozo norte",
    "severity": "high",
    "openedAtIso": "2026-11-20T13:10:00Z",
    "acknowledged": false
  }
]

Campos de cada elemento (tipo Alarma):

CampoTipoQué es
idtextoIdentificador de la alarma.
measurementPointIdtextoEl punto, como texto.
measurementPointNametextoNombre del punto.
severitycritical o high o medium o lowGravedad de la alarma.
openedAtIsotextoFecha y hora UTC.
acknowledgedsí o noSi alguien ya la reconoció.

5.4 GET /series: La serie de uno o varios elementos

Hasta 8 elementos y 20.000 puntos por consulta. El rango máximo depende de la resolución: raw 7 días, minute 3 días, hour 93 días. Un punto que no alcanza el mínimo de muestras viaja SIN valores (sufficient en false): no se entrega un promedio que no es confiable.

ParámetroTipoObligatorioQué es
elementIdslista de enteros (1 a 8), separados por comasíLos ids de los elementos (de /measurement-points), de 1 a 8, separados por coma o repitiendo el parámetro.
fromfecha y hora UTCsíInicio del rango (incluido), en UTC.
tofecha y hora UTCsíFin del rango. Tiene que ser posterior a from.
grainraw o minute o hoursíLa resolución.
curl -s -H "Authorization: Bearer $DYNA_CLAVE" \
  "$DYNA_URL/series?elementIds=101,102&from=2026-11-20T00:00:00Z&to=2026-11-21T00:00:00Z&grain=hour"

Respuesta 200 (valores de ejemplo):

[
  {
    "elementId": 101,
    "tsIso": "2026-11-20T07:00:00Z",
    "samples": 12,
    "discarded": 0,
    "sufficient": true,
    "quality": null,
    "minValue": -2.1,
    "maxValue": 0.4,
    "avgValue": -0.8
  }
]

Campos de cada elemento (tipo PuntoDeSerie):

CampoTipoQué es
elementIdenteroEl elemento al que pertenece el punto.
tsIsotextoFecha y hora UTC.
samplesenteroCuántas mediciones representa el punto.
discardedenteroCuántas mediciones se descartaron por no ser confiables.
sufficientsí o nofalse cuando el punto no alcanza el mínimo de muestras: entonces no trae valores.
qualitytexto o nuloSolo en raw.
minValuenúmero o nuloMínimo del intervalo. Nulo si no hay datos suficientes.
maxValuenúmero o nuloMáximo del intervalo. Nulo si no hay datos suficientes.
avgValuenúmero o nuloPromedio del intervalo. Nulo si no hay datos suficientes.

5.5 GET /receptions: Las tramas que llegaron, por orden de llegada

Para ponerse al día sin depender de un webhook. Cada recepción dice qué equipo entregó, cuándo llegó a la plataforma (receivedAtIso) y qué rango de MEDICIÓN cubre (fromIso a toIso); en satelital esas horas pueden estar a varias horas de distancia. No trae valores: se piden a /series con grain=raw, los elementIds de la recepción, from igual a fromIso y to un instante después de toIso.

Se guarda el cursor de la respuesta y se manda en after la próxima vez. Si more es true, quedaron recepciones por el límite y conviene volver a pedir en seguida. Una recepción aparece unos segundos después de procesada, y se guarda 30 días.

ParámetroTipoObligatorioQué es
afterenteronoEl cursor de la respuesta anterior. Sin él, desde la recepción más antigua guardada. Por omisión 0.
limitenteronoCuántas recepciones como máximo, de 1 a 500. Entre 1 y 500. Por omisión 100.
curl -s -H "Authorization: Bearer $DYNA_CLAVE" "$DYNA_URL/receptions?after=0&limit=100"

Respuesta 200 (valores de ejemplo):

{
  "cursor": "15234",
  "more": false,
  "receptions": [
    {
      "cursor": "15234",
      "deviceId": "4821",
      "deviceIdentifier": "9001",
      "measurementPointId": "310",
      "measurementPointName": "Pozo norte",
      "receivedAtIso": "2026-11-20T13:04:11Z",
      "fromIso": "2026-11-20T07:00:00Z",
      "toIso": "2026-11-20T12:00:00Z",
      "readings": 72,
      "elementIds": ["101", "102", "103"]
    }
  ]
}

La respuesta (tipo Recepciones):

CampoTipoQué es
cursortextoLo que se manda en after la próxima vez. Avanza aunque alguna recepción quede fuera del alcance de la clave.
moresí o notrue si quedaron recepciones sin entregar por el límite.
receptionslista de Recepcion

Cada recepción (tipo Recepcion):

CampoTipoQué es
cursortextoPosición de esta recepción en el orden de llegada.
deviceIdtextoEl equipo, como texto.
deviceIdentifiertextoEl identificador impreso en el equipo.
measurementPointIdtextoEl punto, como texto.
measurementPointNametextoNombre del punto.
receivedAtIsotextoFecha y hora UTC. Cuando la trama llegó a la plataforma.
fromIsotextoFecha y hora UTC. La medición más antigua de la trama (hora del equipo).
toIsotextoFecha y hora UTC. La medición más nueva de la trama (hora del equipo).
readingsenteroCuántas lecturas trajo.
elementIdslista de textoLos elementos que recibieron lecturas; son los ids que pide /series.

5.6 GET /openapi.yaml: Esta especificación

Se publica SIN clave.

Se publica sin clave.

curl -s "$DYNA_URL/openapi.yaml"

6. Recorrido de ejemplo

Los valores de las respuestas son de ejemplo. La forma es la del contrato.

Paso 1. Los puntos de medición y sus elementos:

curl -s -H "Authorization: Bearer $DYNA_CLAVE" "$DYNA_URL/measurement-points"

Del resultado se toma el id de cada elemento (por ejemplo 101).

Paso 2. Las mediciones de un día, una por una:

curl -s -H "Authorization: Bearer $DYNA_CLAVE" \
  "$DYNA_URL/series?elementIds=101&from=2026-11-20T00:00:00Z&to=2026-11-21T00:00:00Z&grain=raw"

Paso 3. Mantenerse al día sin repetir lo ya leído, con el cursor:

curl -s -H "Authorization: Bearer $DYNA_CLAVE" "$DYNA_URL/receptions?after=0&limit=100"

Un script mínimo en Python, sin librerías externas:

import json, os, urllib.request

URL = os.environ["DYNA_URL"]
CLAVE = os.environ["DYNA_CLAVE"]

def get(ruta):
    req = urllib.request.Request(URL + ruta, headers={"Authorization": "Bearer " + CLAVE})
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.load(r)

cursor = "0"
while True:
    pagina = get(f"/receptions?after={cursor}&limit=100")
    for r in pagina["receptions"]:
        print(r["deviceIdentifier"], r["receivedAtIso"], r["fromIso"], r["toIso"], r["readings"])
    cursor = pagina["cursor"]
    if not pagina["more"]:
        break

7. Errores

Todos los errores tienen la forma de problema (RFC 9457) y un code estable, para programar contra el código y no contra el texto:

{"status":401,"code":"api-key-invalid","detail":"La clave de API falta o no es valida."}
EstadocodeQué significa
400invalid-request, too-many-pointsParámetros inválidos: demasiados elementos, resolución desconocida, rango al revés o más largo que el máximo, más de 20.000 puntos, cursor negativo o limit fuera de rango.
401api-key-invalidLa clave falta, no tiene la forma de una clave, no existe o fue revocada.
403api-key-read-only, tenant-suspendedVerbo distinto de GET, o cuenta suspendida.
404El elemento no existe o está fuera del alcance de la clave. Se responde igual en los dos casos.
429api-key-rate-limitSe superó el límite por minuto. La cabecera Retry-After indica cuántos segundos faltan.
503El almacén de series no responde. No equivale a una serie vacía: reintente más tarde.

8. Límites

QuéLímite
Consultas a la API600 por clave por minuto de reloj (valor por omisión). Superado el límite: 429 con Retry-After.
/series, elementos por consultaDe 1 a 8.
/series, puntos por consulta20.000.
/series, rango con grain=raw7 días.
/series, rango con grain=minute3 días.
/series, rango con grain=hour93 días.
/receptions, limitDe 1 a 500 (100 por omisión).
/receptions, retención30 días.

9. Soporte

Para consultas técnicas sobre esta API, escriba a su contacto en Dynasystem. Indique la ruta consultada, la hora de la llamada (UTC) y el code de la respuesta, si lo hubo.