Descripción general de la API HTTP

Todo DTVSOL Super Router responde a una API HTTP. La sirve el demonio del router, dtvsold, y es la que usan la CLI dtvsol, el monitor de OLT y su sistema de facturación para leer y modificar el router. Esta página cubre lo que todos los endpoints tienen en común. Las páginas siguientes cubren un área cada una.

Página	Cubre
Clientes	Clientes por MAC, sus planes, suspensión y fechas de vencimiento
Servicios	Servicios de suscriptor (ONT, VLAN, dirección y velocidad en una sola llamada)
Redes	Redes servidas, DHCP, pools IPv6, delegación de prefijos, DNS
VLAN, direcciones IP, rutas	Interfaces VLAN, direcciones, rutas estáticas, pools de NAT
Planes	Planes de velocidad
OLT	Operaciones de OLT y el registro de OLT
CGNAT y anti-spoofing	NAT de nivel de operador (CGNAT) y vinculación IP/MAC/VLAN
Protección	Lista de permitidos, fail2ban, reenvío de puertos, vista del firewall, Option 82, agente SNMP
Configuración de red	Los puertos, bonds, VLAN y direcciones propios del router, con reversión automática a los 120 s
Alarmas y salud	El registro de alarmas y las lecturas de cada área
Sistema	Estado, doctor, alertas, respaldo, versiones de configuración, gráficas, licencia
API compatible con MikroTik	El listener RouterOS-API para sistemas de facturación (TCP 8728)

URL base

http://ROUTER-IP:8880

La API escucha en la dirección y el puerto definidos en la configuración del router (listen_ip y listen_port). El puerto predeterminado es 8880. dtvsold habla HTTP simple. Si necesita TLS, coloque la API detrás de un proxy inverso o de una VPN.

El puerto de la API está protegido por la lista de permitidos del router. Solo las redes de esa lista pueden conectarse a él (y al monitor de OLT en el puerto 8881). Administre la lista con dtvsol protect, /protect o en Settings → Protection del monitor. Mientras la lista esté vacía, ambos puertos están abiertos para todos, así que agregue sus redes de administración antes de que el router entre en producción. Mantenga la lista lo más pequeña posible.

Autenticación

Cada solicitud necesita la clave de API del router. La clave es api_key en la configuración del router. Envíela en el encabezado X-API-Key:

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

Solo cuando un cliente no pueda definir encabezados, envíela en su lugar como parámetro de consulta:

curl -s "http://ROUTER-IP:8880/status?api_key=YOUR_API_KEY"

Prefiera el encabezado. Las URL terminan en los registros y en el historial del shell. El router compara la clave en tiempo constante. Un router sin clave configurada rechaza todas las solicitudes.

Una solicitud sin una clave válida recibe:

{
    "error": "Unauthorized. Provide X-API-Key header or ?api_key= parameter."
}

con el estado 401 (el texto dice: no autorizado; proporcione el encabezado X-API-Key o el parámetro ?api_key=). El router registra cada intento fallido con la dirección de quien llama en su registro de autenticación, enmascarando cualquier valor pass, password o api_key de la URL. fail2ban vigila este registro, por lo que los fallos repetidos bloquean a quien llama (consulte fail2ban).

Solicitudes

• Rutas. El primer segmento de la ruta es el recurso y el segundo es su parámetro: /clients/AA:BB:CC:DD:EE:FF, /olts/olt-1, /services/svc_1a2b3c/suspend. Las barras finales se ignoran. Codifique en URL los parámetros de ruta cuando sea necesario.
• Los parámetros de consulta se usan como filtros en GET (/clients?network=10.110.0.0/21).
• Los cuerpos de solicitud son objetos JSON. Envíelos con Content-Type: application/json. Un cuerpo que no sea un objeto JSON se trata como vacío. El cuerpo más grande que el router lee es de 4 MiB; uno mayor recibe 413.
• Métodos. Las lecturas son GET. Los cambios son POST (y PUT donde una página lo indique) o DELETE. Algunos endpoints DELETE aceptan un cuerpo JSON. Cada página indica el método de cada endpoint.
• Las credenciales de la OLT nunca van en una URL. POST /olt/{op} rechaza cualquier otro método (consulte OLT).

Los endpoints que modifican el router están marcados en cada página con un recuadro Modifica el router.

Respuestas

Toda respuesta es JSON, con formato legible, sangría de cuatro espacios y seguida de un salto de línea. Las gráficas (PNG) y la descarga del respaldo (un archivo comprimido) son las únicas excepciones.

El router escribe JSON como lo hacía su API original en PHP. Cualquier parser JSON lo lee sin problemas, pero conviene conocer tres costumbres:

• Las barras dentro de las cadenas se escapan: "10.110.0.0\/21" es la cadena 10.110.0.0/21.
• Un objeto vacío puede volver como []. Trate igual un [] vacío y un {}.
• Un número de punto flotante con valor entero se escribe como entero (8, no 8.0).

La mayoría de las respuestas que modifican algo incluyen ok, y muchas incluyen code y message:

{
    "ok": true,
    "code": 201,
    "message": "Client added successfully",
    "client": { "mac": "AA:BB:CC:DD:EE:FF", "ip": "10.110.0.2" }
}

Errores y códigos de estado

Una respuesta de error tiene un texto error. Normalmente también tiene "ok": false y el code repetido en el cuerpo:

{
    "ok": false,
    "code": 409,
    "error": "MAC AA:BB:CC:DD:EE:FF already registered"
}

Estado	Significado
200	Éxito (lecturas y la mayoría de los cambios)
201	Creado (por ejemplo un cliente, un servicio, una versión de configuración guardada)
400	Falta un parámetro o no es válido. El texto de error indica cuál.
401	Sin clave de API, o con la clave incorrecta
404	El cliente, servicio, OLT, plan u operación no existe
405	El método no está permitido en esta ruta. El texto de error suele enumerar las formas válidas.
409	Conflicto: el elemento ya existe, o (en configuración de red) su version está desactualizada
413	Cuerpo de la solicitud mayor de 4 MiB
500	El router no pudo completar el cambio (falló un comando, no se pudo escribir un archivo). El texto de error indica qué falló, a menudo con un detail.

Cuando una respuesta 5xx se debe a un documento de configuración que no se puede analizar, la respuesta también enumera los archivos dañados en broken_data_files. dtvsol doctor informa el mismo problema.

Una ruta que no es un recurso de la API recibe una respuesta 200 con el resumen de uso integrado de la API, no un 404. Si ve una respuesta con "api": "DTVSOL DHCP API v1.0", verifique que escribió correctamente el recurso.

La API de acciones

Para clientes que solo pueden emitir solicitudes GET simples (un navegador, un sistema de facturación con callbacks por URL), la mayoría de las operaciones también existen como acciones. El nombre de la acción y todos los argumentos van en la cadena de consulta:

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "http://ROUTER-IP:8880/api?action=get&mac=AA:BB:CC:DD:EE:FF"

Cada acción llama al mismo código que su endpoint REST, por lo que el efecto es idéntico. Prefiera REST para integraciones nuevas: mantiene los cambios fuera de las solicitudes GET y las credenciales fuera de las URL. Para la OLT en especial, use POST /olt/{op}.

Las acciones que modifican el router funcionan con GET. La única excepción es config-save, que debe ser POST. Una acción desconocida recibe 400 con "error": "Unknown action" (acción desconocida) y una breve lista de acciones.

Acción	Parámetros de consulta	Equivale a
action=list	[network]	GET /clients
action=search	q	GET /clients?q=
action=get	mac	GET /clients/{mac}
action=add	mac, ip, [hostname], [comment], [ipv6]	POST /clients
action=delete	mac	DELETE /clients/{mac}
action=active, action=connected	[state]	GET /clients/active
action=clients6	[iface], [routers=1]	GET /clients6
action=ip-info	[network]	GET /ips
action=set-plan	mac, plan	POST /plan
action=suspend, action=resume	mac	POST /suspend, POST /resume
action=set-expires	mac, expires	POST /expires
action=status		GET /status
action=networks		GET /networks
action=reload		POST /dhcp/reload
action=interfaces		GET /interfaces
action=iface-list		GET /iface
action=add-net, action=remove-net	iface, [label]	POST /net, DELETE /net
action=net6-add, action=net6-del	iface	POST /net6, DELETE /net6
action=net6-pool	iface, [start], [end]	POST /net6/pool
action=net6-lease	valid, [preferred]	POST /net6/lease
action=net6-dns	servers, [domain], [clear_domain=1]	Solo los resolutores DHCPv6 (dns-set define ambos)
action=pd-list		GET /pd
action=pd-add	iface, [size]	POST /pd
action=pd-resize	iface, size	POST /pd/resize
action=pd-del	iface	DELETE /pd
action=pd-assign, action=pd-unassign	mac, [prefix]	fijación de la delegación de prefijos
action=pd-sync	[dry=1]	conciliar ahora las rutas de prefijos delegados
action=dns-list		GET /dns
action=dns-set	[v4], [v6], [domain], [iface], [apply=all]	POST /dns, POST /dns/{iface}
action=dns-del	iface o global=v4|v6|domain|all	DELETE /dns/{iface}, DELETE /dns
action=vlan-list		GET /vlans
action=vlan-add	parent, vlan_id, [ip], [ipv6], [label], [protocol], [force=1], [serve=0]	POST /vlans
action=vlan-disable	name, [reason]	POST /vlans/disable
action=vlan-enable	name	POST /vlans/enable
action=vlan-del	name	DELETE /vlans
action=ip-add, action=ip-del	iface, ip, [force=1]	POST /ip, DELETE /ip
action=route-list, action=route-add, action=route-del	prefix, [via], [dev], [comment]	/routes
action=nat-list, action=nat-add, action=nat-del	iface, pool_start, pool_end, [exempt], [comment]	/nat
action=plan-list		GET /plans
action=plan-add	name, down_mbps, up_mbps, [comment]	POST /plans
action=plan-del	name	DELETE /plans/{name}
action=service-list	[state], [olt], [q], [fast=1]	GET /services
action=service-get	id	GET /services/{id}
action=service-add	como en POST /services, en la consulta	POST /services
action=service-set	id, campos como en POST /services/{id}	POST /services/{id}
action=service-suspend, action=service-resume	id	POST /services/{id}/suspend, /resume
action=service-del	id, [keep_ont=1]	DELETE /services/{id}
action=service-unregistered	[olt]	GET /services/unregistered
action=service-expiry		aplicar ahora las fechas de vencimiento de los servicios (el temporizador del router lo hace por sí solo)
action=olts-list		GET /olts
action=olts-add, action=olts-set	name, campos de la OLT	POST /olts, POST /olts/{name}
action=olts-del	name	DELETE /olts/{name}
action=olt-sync	[olt], [dry_run=1]	POST /olt/sync
action=olt-backup	[olt]	POST /olt/backup
action=olt-backups	[olt], [n]	GET /olt/backups
action=olt-diff	[olt], [rev], [to]	GET /olt/diff
action=olt-info, action=olt-autofind, … (olt-<op>)	olt=<name> y los argumentos de la operación	POST /olt/{op}
action=protect-list		GET /protect
action=protect-add	network, [comment]	POST /protect
action=protect-delete	network	DELETE /protect
action=firewall	[network]	GET /firewall
action=firewall-full		GET /firewall/full
action=fail2ban, action=fail2ban-status		GET /fail2ban
action=fail2ban-unban	ip	POST /fail2ban
action=pf-list, action=pf-add, action=pf-del	como en /pf, en la consulta	/pf
action=option82		GET /option82
action=snmp-status, action=snmp-set	como en /snmp, en la consulta	/snmp
action=cgnat-status, action=cgnat-set	como en /cgnat, en la consulta	/cgnat
action=cgnat-lookup	public_ip, port	GET /cgnat/lookup
action=antispoof-status		GET /antispoof
action=antispoof-set	enabled, [mode], [log], [exempt]	POST /antispoof
action=antispoof-iface	iface, mode	POST /antispoof/{iface}
action=antispoof-log	[since], [limit]	GET /antispoof/log
action=antispoof-sync		POST /antispoof/sync
action=doctor	[olt=1]	GET /doctor
action=alerts		GET /alerts
action=config-status, action=config-versions, action=config-diff, action=config-show	consulte Sistema	versiones de configuración
action=config-save (POST)	[comment]	guardar la configuración en ejecución como una nueva versión

Las operaciones de OLT disponibles como olt-<op> son: action=olt-info, action=olt-autofind, action=olt-onus, action=olt-vlans, action=olt-serviceports, action=olt-profiles, action=olt-config, action=olt-run, action=olt-exec, action=olt-vlan-add, action=olt-vlan-del, action=olt-port-vlan, action=olt-profile-add, action=olt-profile-del, action=olt-ont-add, action=olt-ont-del, action=olt-ont-reboot, action=olt-ont-desc, action=olt-ont-optical, action=olt-ntp, action=olt-sysname, action=olt-save, action=olt-plan-sync y action=olt-init. Cualquier otra operación de la lista de GET /olt se acepta de la misma forma.

Las áreas más recientes no tienen forma de acción: el registro de alarmas y las lecturas de salud, la configuración de red del router, las gráficas, la descarga del respaldo y la restauración.

Verificación de la documentación frente al código

El repositorio del sitio incluye tools/api-inventory.mjs. Lee las fuentes de dtvsold y enumera cada recurso, endpoint y acción que la API enruta. Con --check, enumera todo lo que estas páginas no documentan. Se ejecuta en cada versión.