Guía de la API de Dynasystem para pruebas
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.
- Es una API REST de solo lectura, en JSON.
- Se autentica con una clave de API.
- Está descrita por una especificación OpenAPI 3.1, de acceso público.
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:
- una cuenta de prueba, con acceso al portal;
- una clave de API (
dsk_...) asociada a esa cuenta, entregada de forma segura; - un equipo de ejemplo con mediciones ya cargadas, para que las consultas devuelvan datos.
Con esos elementos, el recorrido básico es el siguiente:
- Verifique que el servicio responde:
curl https://app.dynasystem.cl/api/v1/external/openapi.yaml. - Liste los puntos de medición de la cuenta con
/measurement-points. De ahí se obtiene el identificador de cada elemento (elementId). - Consulte las tramas recibidas con
/receptions. - Pida los valores de un elemento con
/series. - Consulte los equipos con
/devicesy 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
- Dirección base:
https://app.dynasystem.cl/api/v1/external - Formato: JSON en UTF-8. Los errores usan
application/problem+json. - Solo lectura: todas las rutas son
GET. Con una clave válida, cualquier otro verbo responde 403api-key-read-only; sin clave, 401. - Horas en UTC, en formato ISO 8601 y con
Zal final:2026-11-20T13:04:11Z. - Dos horas por cada dato: la hora de medición (cuando el equipo midió) y la hora de llegada (
receivedAtIso, cuando la trama llegó a la plataforma). - Identificadores como texto (
"id": "310"), salvo loselementIdde una serie, que son números. - Alcance: una clave accede a los datos de una sola cuenta y, si se creó con alcance limitado, solo a los sitios que se le asignaron. Un recurso fuera de ese alcance responde 404, igual que uno inexistente.
- Especificación OpenAPI 3.1, sin clave, en
GET /openapi.yaml(versión 1.1.0). Puede importarse en herramientas como Postman o Insomnia, o usarse para generar un cliente.
4. Autenticación
La API se autentica con una clave de API. No requiere OAuth ni usuario y contraseña.
La clave:
- empieza con
dsk_y tiene 47 caracteres; - se crea en el portal, en Salidas, pestaña Claves de API, y se muestra una sola vez al crearla;
- se puede revocar en cualquier momento;
- puede limitarse a ciertos sitios.
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):
| Campo | Tipo | Qué es |
|---|---|---|
id | texto | Identificador del punto. |
name | texto | Nombre. |
siteId | texto | El sitio donde está el punto. |
siteZone | texto | La zona horaria del sitio (por ejemplo America/Santiago). |
elements | lista de Elemento | Las 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):
| Campo | Tipo | Qué es |
|---|---|---|
id | texto | Identificador interno del equipo. |
identifier | texto | El identificador impreso en el equipo. |
status | active o revoked | Estado del equipo: activo o revocado. |
measurementPointId | texto o nulo | El punto donde está instalado, o nulo si no lo está. |
measurementPointName | texto o nulo | Nombre 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):
| Campo | Tipo | Qué es |
|---|---|---|
id | texto | Identificador de la alarma. |
measurementPointId | texto | El punto, como texto. |
measurementPointName | texto | Nombre del punto. |
severity | critical o high o medium o low | Gravedad de la alarma. |
openedAtIso | texto | Fecha y hora UTC. |
acknowledged | sí o no | Si 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ámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
elementIds | lista de enteros (1 a 8), separados por coma | sí | Los ids de los elementos (de /measurement-points), de 1 a 8, separados por coma o repitiendo el parámetro. |
from | fecha y hora UTC | sí | Inicio del rango (incluido), en UTC. |
to | fecha y hora UTC | sí | Fin del rango. Tiene que ser posterior a from. |
grain | raw o minute o hour | sí | 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):
| Campo | Tipo | Qué es |
|---|---|---|
elementId | entero | El elemento al que pertenece el punto. |
tsIso | texto | Fecha y hora UTC. |
samples | entero | Cuántas mediciones representa el punto. |
discarded | entero | Cuántas mediciones se descartaron por no ser confiables. |
sufficient | sí o no | false cuando el punto no alcanza el mínimo de muestras: entonces no trae valores. |
quality | texto o nulo | Solo en raw. |
minValue | número o nulo | Mínimo del intervalo. Nulo si no hay datos suficientes. |
maxValue | número o nulo | Máximo del intervalo. Nulo si no hay datos suficientes. |
avgValue | número o nulo | Promedio 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ámetro | Tipo | Obligatorio | Qué es |
|---|---|---|---|
after | entero | no | El cursor de la respuesta anterior. Sin él, desde la recepción más antigua guardada. Por omisión 0. |
limit | entero | no | Cuá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):
| Campo | Tipo | Qué es |
|---|---|---|
cursor | texto | Lo que se manda en after la próxima vez. Avanza aunque alguna recepción quede fuera del alcance de la clave. |
more | sí o no | true si quedaron recepciones sin entregar por el límite. |
receptions | lista de Recepcion |
Cada recepción (tipo Recepcion):
| Campo | Tipo | Qué es |
|---|---|---|
cursor | texto | Posición de esta recepción en el orden de llegada. |
deviceId | texto | El equipo, como texto. |
deviceIdentifier | texto | El identificador impreso en el equipo. |
measurementPointId | texto | El punto, como texto. |
measurementPointName | texto | Nombre del punto. |
receivedAtIso | texto | Fecha y hora UTC. Cuando la trama llegó a la plataforma. |
fromIso | texto | Fecha y hora UTC. La medición más antigua de la trama (hora del equipo). |
toIso | texto | Fecha y hora UTC. La medición más nueva de la trama (hora del equipo). |
readings | entero | Cuántas lecturas trajo. |
elementIds | lista de texto | Los 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"
- Guarde el
cursorde la respuesta y envíelo enafteren la siguiente consulta. - Si
moreestrue, quedaron recepciones por el límite: repita la consulta de inmediato. - Para cada recepción, pida
/seriescongrain=raw, suselementIds(de a 8 como máximo),fromigual afromIsoytoun instante después detoIso. El extremotoes exclusivo.
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"]:
break7. 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."}| Estado | code | Qué significa |
|---|---|---|
| 400 | invalid-request, too-many-points | Pará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. |
| 401 | api-key-invalid | La clave falta, no tiene la forma de una clave, no existe o fue revocada. |
| 403 | api-key-read-only, tenant-suspended | Verbo distinto de GET, o cuenta suspendida. |
| 404 | El elemento no existe o está fuera del alcance de la clave. Se responde igual en los dos casos. | |
| 429 | api-key-rate-limit | Se superó el límite por minuto. La cabecera Retry-After indica cuántos segundos faltan. |
| 503 | El 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 API | 600 por clave por minuto de reloj (valor por omisión). Superado el límite: 429 con Retry-After. |
/series, elementos por consulta | De 1 a 8. |
/series, puntos por consulta | 20.000. |
/series, rango con grain=raw | 7 días. |
/series, rango con grain=minute | 3 días. |
/series, rango con grain=hour | 93 días. |
/receptions, limit | De 1 a 500 (100 por omisión). |
/receptions, retención | 30 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.