API del sistema

Los endpoints de esta página describen el router en su conjunto: su estado, sus comprobaciones de salud, sus copias de seguridad y versiones guardadas de la configuración, y las gráficas de tráfico que dibuja. Para la URL base, la autenticación y el formato de los errores, consulte la descripción general de la API.

Estado y comprobaciones

GET /status

Un resumen del router en una sola llamada: versión, si el servicio DHCP está en ejecución, cuántos clientes heredados por MAC están registrados y en línea, clientes por red y el modo de anti-spoofing.

curl -s http://ROUTER-IP:8880/status -H "X-API-Key: YOUR_API_KEY"

{
    "api": "DTVSOL DHCP API v1.0",
    "router_version": "2026.09.27",
    "dhcp_service": "running",
    "total_clients": 42,
    "online_clients": 37,
    "per_network": {
        "10.110.0.0/21": 42
    },
    "interfaces": 6,
    "antispoof": "strict",
    "server_time": "2026-09-28 10:15:00"
}

antispoof es el modo configurado (strict o dynamic) cuando el anti-spoofing está habilitado; en caso contrario, off. online_clients cuenta los clientes cuya dirección es en este momento un vecino activo del router.

GET /doctor

El doctor de configuración: una auditoría completa de la configuración del router y de lo que sobrevive a un reinicio (direcciones, VLAN, configuración de DHCP y de anuncios de router, archivos de datos, el almacén de configuración, NTP para las OLT). Con ?olt=1 también comprueba cada OLT registrada contra los registros del router. Solo lee.

Nombre	En	Tipo	Notas
olt	query	boolean	1 también comprueba las OLT registradas (más lento). Si se omite: solo el router.

curl -s "http://ROUTER-IP:8880/doctor?olt=1" -H "X-API-Key: YOUR_API_KEY"

{
    "ok": true,
    "code": 200,
    "generated": "2026-09-28 10:15:00",
    "count": 1,
    "counts": {
        "critical": 0,
        "warning": 1,
        "info": 0
    },
    "findings": [
        {
            "severity": "warning",
            "area": "dhcp",
            "problem": "…",
            "detail": "…",
            "fix": "…"
        }
    ]
}

ok es true cuando no hay hallazgos critical. Cada hallazgo incluye una severity (critical, warning o info), el area a la que se refiere, el problem, un detail y una corrección sugerida en fix. El estado HTTP es siempre 200; lea ok y counts.

El equivalente en la CLI es dtvsol doctor (con las comprobaciones de OLT) o dtvsol doctor --no-olt.

GET /alerts

Las condiciones que merecen atención en este momento: el servicio DHCP detenido, enlaces VLAN caídos, pools de direcciones casi llenos, el pool de CGNAT, descartes de anti-spoofing, dispositivos desconocidos, problemas de OLT y de fibra reportados por el colector de OLT, y la licencia. Solo lee.

curl -s http://ROUTER-IP:8880/alerts -H "X-API-Key: YOUR_API_KEY"

{
    "count": 2,
    "generated": "2026-09-28 10:15:00",
    "alerts": [
        {
            "severity": "critical",
            "type": "dhcp",
            "message": "DHCP service is not running"
        },
        {
            "severity": "warning",
            "type": "olt",
            "olt": "olt-1",
            "message": "OLT olt-1: …"
        }
    ]
}

severity es critical, warning o info. type es uno de dhcp, interface, dhcp-pool, stranger, cgnat, spoof, olt, fiber o licence; las alertas de OLT y de fibra también indican la olt (y, en el caso de la fibra, el puerto y la ONT).

Para alarmas con historial (activadas, despejadas, reconocidas), consulte la API de alarmas y salud.

Copia de seguridad y restauración

GET /backup

Descarga una copia de seguridad completa del router como un archivo .tar.gz: los directorios etc/ y data/, con la base de datos de configuración incluida como una copia consistente tomada en ese momento. La respuesta es el propio archivo (Content-Type: application/gzip, con un nombre de archivo en Content-Disposition como dtvsol-router-backup-20260928-101500.tar.gz).

Nota

El archivo contiene la configuración del router, incluidas la clave de API y las credenciales selladas de las OLT. Guárdelo con la misma seguridad que el propio router.

curl -s http://ROUTER-IP:8880/backup -H "X-API-Key: YOUR_API_KEY" -OJ

En caso de fallo, la respuesta es JSON con estado 500:

{
    "error": "Backup failed",
    "detail": "…"
}

El equivalente en la CLI es dtvsol backup [outfile.tar.gz].

POST /restore

Modifica el router

Reemplaza la configuración del router con el contenido de un archivo de copia de seguridad y vuelve a aplicar todos los servicios.

Restaura un archivo de copia de seguridad que ya se encuentra en el router (súbalo primero, por ejemplo con scp). Antes de desempaquetarlo, la configuración actual se guarda como una nueva versión de configuración, de modo que la propia restauración puede deshacerse con dtvsol config restore <undo_version> --yes. Después de desempaquetarlo, el router reescribe los archivos de hosts de DHCP y vuelve a aplicar el control de ancho de banda, la contabilidad, CGNAT, los reenvíos de puertos, el anti-spoofing y las reglas del firewall.

Nombre	En	Tipo	Notas
file	body	string	Ruta del archivo .tar.gz en el router. Obligatorio.

curl -s -X POST http://ROUTER-IP:8880/restore \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file": "/root/dtvsol-router-backup-20260928-101500.tar.gz"}'

{
    "ok": true,
    "code": 200,
    "message": "Restored and services reapplied",
    "documents": ["clients", "services"],
    "undo_version": 57
}

Errores: 400 cuando falta el archivo ("Provide an existing backup file path (upload it to the router first)", es decir, indique la ruta de un archivo de copia de seguridad existente y súbalo primero al router) o no es un tar.gz válido; 500 cuando falla la extracción, o cuando el archivo se desempaquetó pero no se pudieron incorporar todos sus documentos de configuración; esa respuesta incluye undo_version y una sugerencia next con el comando que regresa a la configuración anterior a la restauración.

El equivalente en la CLI es dtvsol restore <file.tar.gz>.

Versiones de configuración (API de acciones)

El router guarda versiones de su configuración en su base de datos, como la configuración guardada en la memoria flash de un switch. Por HTTP solo se accede a ellas mediante la API de acciones (/api?action=…); los parámetros van en la cadena de consulta o, para POST, en un cuerpo JSON (el cuerpo tiene prioridad; la cadena de consulta completa lo que le falte al cuerpo). El equivalente en la CLI es dtvsol config ….

Acción	Método	Parámetros	Qué hace
action=config-status	GET	—	Con qué versión guardada coincide la configuración en ejecución, el id de la versión más reciente y si hay cambios sin guardar (archivos añadidos, eliminados, modificados).
action=config-versions	GET	n (predeterminado 30, 1–1000)	Las versiones guardadas más recientes: id, saved_at, saved_by, comment, auto, files, bytes, digest.
action=config-save	POST	comment (opcional, hasta 200 caracteres)	Modifica el router: guarda la configuración en ejecución como una nueva versión. Un GET se rechaza con 405. Responde 201.
action=config-diff	GET	from (id de versión, obligatorio), to (id de versión o running, predeterminado running)	Qué cambió entre dos versiones, o entre una versión y la configuración en ejecución.
action=config-show	GET	id (id de versión, obligatorio), path (opcional)	Sin path: la lista de archivos de esa versión. Con path: el contenido de ese archivo, con contraseñas, claves y tokens enmascarados.

La restauración de una versión guardada se realiza desde la CLI: dtvsol config restore <id> --yes.

curl -s "http://ROUTER-IP:8880/api?action=config-status" -H "X-API-Key: YOUR_API_KEY"

{
    "ok": true,
    "saved": {
        "id": 57,
        "saved_at": "2026-09-28 09:00:00",
        "comment": "before maintenance"
    },
    "latest": 57,
    "unsaved": true,
    "changes": {
        "added": [],
        "removed": [],
        "changed": ["data/services.json"]
    },
    "code": 200
}

curl -s -X POST "http://ROUTER-IP:8880/api?action=config-save" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment": "new plans for October"}'

{
    "ok": true,
    "saved": true,
    "version": 58,
    "files": 24,
    "message": "…",
    "code": 201
}

curl -s "http://ROUTER-IP:8880/api?action=config-diff&from=57&to=running" -H "X-API-Key: YOUR_API_KEY"

{
    "ok": true,
    "from": 57,
    "to": "running",
    "changes": {
        "added": [],
        "removed": [],
        "changed": ["data/services.json"]
    },
    "diff": "…",
    "code": 200
}

curl -s "http://ROUTER-IP:8880/api?action=config-show&id=57" -H "X-API-Key: YOUR_API_KEY"

{
    "ok": true,
    "version": 57,
    "files": ["etc/config.php", "data/services.json"],
    "code": 200
}

Errores: 400 cuando falta from/id o no es numérico, o cuando to no es ni un id de versión ni running; 404 para una versión (o un archivo dentro de una versión) que no existe; 500 cuando no se puede leer el almacén.

Gráficas de tráfico

Las gráficas se devuelven como imágenes PNG (Content-Type: image/png). Cuando no se puede dibujar ninguna gráfica, la respuesta es JSON: {"error": "…"} con estado 400 (parámetros incorrectos), 404 (aún no hay datos; las muestras se recogen cada minuto) o 500 (falló el dibujo).

GET /graph/{name}

Tráfico de un suscriptor o de una interfaz. {name} es un id de servicio (svc_ seguido de 8 dígitos hexadecimales), la dirección MAC de un cliente o el nombre de una interfaz (por ejemplo vlan100).

Nombre	En	Tipo	Notas
name	path	string	Id de servicio, dirección MAC o nombre de interfaz.
period	query	string	hour (últimas 3 horas), day (predeterminado), week, month o year.

curl -s "http://ROUTER-IP:8880/graph/vlan100?period=week" \
  -H "X-API-Key: YOUR_API_KEY" -o graph.png

GET /graph/oltport

Tráfico de un puerto PON de la OLT, de un puerto de uplink o de una tarjeta completa (todos sus puertos), a partir de las muestras del colector de OLT.

Nombre	En	Tipo	Notas
olt	query	string	Nombre de la OLT registrada. Obligatorio.
port	query	string	F/S/P para un puerto, o F/S para una tarjeta completa. Obligatorio.
pon	query	boolean	1 (predeterminado): un puerto PON; 0: un puerto de uplink.
period	query	string	hour, day (predeterminado), week, month, quarter, year o 2years.

curl -s "http://ROUTER-IP:8880/graph/oltport?olt=olt-1&port=0/1/3&period=month" \
  -H "X-API-Key: YOUR_API_KEY" -o graph.png

GET /graph/ont

Tráfico o contadores de errores de una ONT, tal como los ve la OLT.

Nombre	En	Tipo	Notas
olt	query	string	Nombre de la OLT registrada. Obligatorio.
port	query	string	Puerto PON F/S/P. Obligatorio.
ont	query	integer	Id de la ONT en ese puerto. Obligatorio.
what	query	string	traffic (predeterminado) o errors.
period	query	string	hour, day (predeterminado), week, month, quarter, year o 2years.

curl -s "http://ROUTER-IP:8880/graph/ont?olt=olt-1&port=0/1/3&ont=12&what=errors" \
  -H "X-API-Key: YOUR_API_KEY" -o graph.png

GET /services/{id}/graph

Tráfico de un servicio. {id} es cualquier dato que identifique el servicio (consulte la API de servicios).

Nombre	En	Tipo	Notas
id	path	string	Id de servicio u otra clave del servicio.
source	query	string	router (predeterminado): tráfico a través del router; olt: tráfico de su ONT según lo cuenta la OLT; errors: los contadores de errores de la ONT.
period	query	string	Para router: hour, day (predeterminado), week, month, year. Para olt/errors: además quarter y 2years.

curl -s "http://ROUTER-IP:8880/services/svc_1a2b3c4d/graph?source=olt&period=week" \
  -H "X-API-Key: YOUR_API_KEY" -o graph.png

Errores: 404 "No such service" (el servicio no existe), o "This service has no ONT" (el servicio no tiene ONT) para source=olt|errors en un servicio sin ONT.

Licencia

La licencia del router no se expone mediante la API HTTP. Se administra en el router con la CLI:

Comando	Qué hace
dtvsol licence status	Muestra si el router está inscrito, el proveedor de la licencia, si la licencia es válida (y, si no, por qué), su fecha de vencimiento con los días restantes, la última renovación (hora y resultado) y una nota sobre el reloj.
dtvsol licence refresh	Obtiene una licencia nueva en este momento (un temporizador también lo hace a diario).
dtvsol licence enrol <id> <token|->	Inscribe el router con el id y el token emitidos para él; - lee el token de la entrada estándar.

Una licencia a punto de vencer o no válida también aparece como una alerta licence en GET /alerts.

Equivalentes en la API de acciones

Acción	Equivale a
action=status	GET /status
action=doctor (&olt=1)	GET /doctor
action=alerts	GET /alerts
action=config-status	dtvsol config status
action=config-versions	dtvsol config versions [n]
action=config-save (POST)	dtvsol config save ["comment"]
action=config-diff	dtvsol config diff <a> [b|running]
action=config-show	dtvsol config show <id> [path]