API de clientes

Un cliente es el registro de abonado heredado basado en MAC: una dirección MAC fijada a una dirección IPv4 fija (y opcionalmente a una dirección IPv6) en una de las redes del router, servida por DHCP, con un plan de velocidad opcional, un indicador de suspensión y una fecha de fin opcional. Las integraciones nuevas que aprovisionan ONT usan en su lugar la API de servicios; los clientes se mantienen para sistemas de facturación y redes identificados por la MAC del CPE.

La URL base, la autenticación (X-API-Key), el formato de errores y la API de acciones se describen en la descripción general de la API.

Las direcciones MAC se aceptan en cualquier forma habitual (aa-bb-cc-dd-ee-ff, aabbccddeeff, AA:BB:CC:DD:EE:FF) y se almacenan en mayúsculas con dos puntos.

Lectura

GET /clients

Lista los clientes registrados, cada uno con las direcciones IPv6 que realmente se le ven usar y cualquier prefijo que se le haya delegado.

Nombre	En	Tipo	Notas
network	query	CIDR	Solo los clientes cuya dirección IPv4 está en esta red, p. ej. 10.110.0.0/21.
q	query	string	Búsqueda sin distinguir mayúsculas y minúsculas en MAC, IP, IPv6, nombre de host, comentario, interfaz y red.

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/clients?network=10.110.0.0/21"

{
  "count": 1,
  "clients": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "ip": "10.110.0.2",
      "ipv6": null,
      "plan": "plan_100_50",
      "suspended": false,
      "auto_suspended": false,
      "expires": null,
      "hostname": "client-aabbccddeeff",
      "network": "10.110.0.0/21",
      "network6": null,
      "iface": "vlan100",
      "gateway": "10.110.0.1",
      "comment": "",
      "created": "2026-09-01 10:00:00",
      "ipv6_actual": "XXXX:XXXX:100::25",
      "ipv6_all": ["XXXX:XXXX:100::25"],
      "ipv6_state": "REACHABLE",
      "prefix6_delegated": []
    }
  ]
}

GET /clients/{mac}

Un cliente. {mac} también puede ser la dirección IPv4 del cliente, su dirección IPv6 o su nombre de host (sin distinguir mayúsculas y minúsculas).

Nombre	En	Tipo	Notas
mac	path	string	MAC, IPv4, IPv6 o nombre de host.

curl -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/clients/AA:BB:CC:DD:EE:FF

{
  "client": {
    "mac": "AA:BB:CC:DD:EE:FF",
    "ip": "10.110.0.2",
    "hostname": "client-aabbccddeeff",
    "network": "10.110.0.0/21",
    "iface": "vlan100",
    "gateway": "10.110.0.1",
    "plan": "plan_100_50",
    "suspended": false,
    "expires": null
  }
}

404 {"error": "Client not found"} (cliente no encontrado) cuando nada coincide.

GET /clients/active

Quién está en línea ahora: cada cliente y cada servicio con su estado de vecino (ARP/NDP), además de las concesiones DHCP dinámicas que no pertenecen a ninguno de ellos. status es online (REACHABLE, DELAY, PROBE, PERMANENT), recent (STALE) u offline. mac_mismatch es true cuando la dirección es respondida por una MAC distinta de la registrada.

Nombre	En	Tipo	Notas
state	query	string	Solo las entradas online, recent u offline (el resumen sigue contando todo).

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/clients/active?state=online"

{
  "summary": {
    "registered": 120,
    "services": 340,
    "online": 401,
    "recent": 12,
    "offline": 47,
    "dynamic_active_leases": 3
  },
  "clients": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "ip": "10.110.0.2",
      "hostname": "client-aabbccddeeff",
      "iface": "vlan100",
      "status": "online",
      "neigh_state": "REACHABLE",
      "seen_mac": "AA:BB:CC:DD:EE:FF",
      "mac_mismatch": false,
      "ipv6_actual": null,
      "ipv6_all": [],
      "prefix6_delegated": []
    },
    {
      "mac": "AA:BB:CC:00:11:22",
      "ip": "100.64.16.9",
      "hostname": "Customer name",
      "iface": "vlan116",
      "status": "online",
      "neigh_state": "REACHABLE",
      "service": "svc_1a2b3c4d",
      "service_state": "active",
      "seen_mac": "AA:BB:CC:00:11:22",
      "mac_mismatch": false
    }
  ],
  "dynamic_leases": [
    {
      "ip": "10.120.0.50",
      "state": "active",
      "mac": "AA:BB:CC:33:44:55",
      "hostname": "cpe",
      "ends": "2026/09/28 12:00:00",
      "neigh_state": "STALE",
      "online": false
    }
  ]
}

GET /clients6

Cada MAC vista en el cable por IPv6 — registrada o no — con la dirección IPv6 que tiene, su concesión DHCPv6, su prefijo fijado y el prefijo que se le ha delegado. Las MAC propias del router se omiten; los demás routers (anuncios de router IPv6) se omiten a menos que se indique routers=1, o a menos que estén registrados o tengan una concesión.

Nombre	En	Tipo	Notas
iface	query	string	Solo esta interfaz, p. ej. vlan100.
routers	query	1	Incluye los routers vecinos.

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/clients6?iface=vlan100"

{
  "summary": { "total": 1, "online": 1, "registered": 1, "with_prefix": 1 },
  "clients": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "registered": true,
      "hostname": "client-aabbccddeeff",
      "ipv4": "10.110.0.2",
      "iface": "vlan100",
      "ipv6": "XXXX:XXXX:100::25",
      "ipv6_all": ["XXXX:XXXX:100::25"],
      "ipv6_reserved": null,
      "link_local": "fe80::aabb:ccff:fedd:eeff",
      "state": "REACHABLE",
      "online": true,
      "router": false,
      "lease6": ["XXXX:XXXX:100::25"],
      "prefix6_pinned": null,
      "prefix6_delegated": ["XXXX:XXXX:b:500::/64"]
    }
  ],
  "orphan_delegated_prefixes": []
}

GET /ips

Uso de direcciones por red en el router: las direcciones registradas, las direcciones no registradas vistas en vivo en el cable y las primeras diez direcciones libres.

Nombre	En	Tipo	Notas
network	query	CIDR	Una red, p. ej. 10.110.0.0/21. Omítalo para todas.

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/ips?network=10.110.0.0/21"

{
  "ok": true,
  "code": 200,
  "count": 1,
  "networks": [
    {
      "network": "10.110.0.0/21",
      "iface": "vlan100",
      "gateway": "10.110.0.1",
      "total_assignable": 2045,
      "used_count": 1,
      "free_count": 2044,
      "next_free": ["10.110.0.3", "10.110.0.4"],
      "used": [ { "ip": "10.110.0.2", "mac": "AA:BB:CC:DD:EE:FF", "hostname": "client-aabbccddeeff" } ],
      "unregistered_seen": [ { "ip": "10.110.0.77", "mac": "AA:BB:CC:66:77:88", "neigh_state": "STALE" } ]
    }
  ]
}

404 cuando la red indicada no está en este router.

Cambios

POST /clients

Modifica el router

Agrega una reserva DHCP, la regla de filtrado MAC y (con un plan) el control de velocidad del cliente; recarga DHCP.

Registra un cliente. La dirección IPv4 debe estar en una red configurada en una de las interfaces del router (y no ser su dirección de red, de gateway ni de broadcast); la red, la interfaz y el gateway se toman de allí. Una dirección IPv6, cuando se indica, debe estar en la misma interfaz.

Nombre	En	Tipo	Notas
mac	body	string	Obligatorio.
ip	body	IPv4	Obligatorio.
ipv6	body	IPv6	Dirección IPv6 fija opcional.
hostname	body	string	Letras, dígitos, puntos, guiones, máx. 63. Predeterminado client-<mac without colons> (la MAC sin dos puntos).
comment	body	string	Texto libre.
plan	body	string	Un nombre de plan existente, o none.
expires	body	date	Fecha de fin (YYYY-MM-DD o YYYY-MM-DD HH:MM), o never.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mac":"AA:BB:CC:DD:EE:FF","ip":"10.110.0.2","hostname":"cpe-1","plan":"plan_100_50"}' \
  http://ROUTER-IP:8880/clients

{
  "ok": true,
  "code": 201,
  "message": "Client added successfully",
  "client": {
    "mac": "AA:BB:CC:DD:EE:FF",
    "ip": "10.110.0.2",
    "ipv6": null,
    "plan": "plan_100_50",
    "suspended": false,
    "auto_suspended": false,
    "expires": null,
    "hostname": "cpe-1",
    "network": "10.110.0.0/21",
    "network6": null,
    "iface": "vlan100",
    "gateway": "10.110.0.1",
    "comment": "",
    "created": "2026-09-28 10:00:00"
  }
}

Errores: 400 MAC/IP/IPv6/nombre de host no válido o una dirección fuera de las redes del router; 404 plan desconocido; 409 MAC, IP, IPv6 o nombre de host ya en uso (para una MAC duplicada la respuesta incluye existing); 500 cuando DHCP no se recarga — en ese caso se revierte el alta del cliente.

DELETE /clients/{mac}

Modifica el router

Elimina la reserva, las reglas de filtrado MAC, cualquier suspensión y el control de velocidad del cliente; recarga DHCP.

Nombre	En	Tipo	Notas
mac	path	string	Obligatorio.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/clients/AA:BB:CC:DD:EE:FF

{
  "ok": true,
  "code": 200,
  "message": "Client deleted",
  "client": { "mac": "AA:BB:CC:DD:EE:FF", "ip": "10.110.0.2", "hostname": "cpe-1" },
  "dhcp": { "ok": true, "message": "DHCP reloaded" }
}

404 cuando el cliente no existe; 400 {"error": "Specify MAC"} (indique la MAC) si falta la MAC.

POST /plan

Modifica el router

Establece el plan de velocidad del cliente y reconstruye el control de velocidad en su interfaz.

Nombre	En	Tipo	Notas
mac	body	string	Obligatorio.
plan	body	string	Un nombre de plan; vacío o none quita el límite.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mac":"AA:BB:CC:DD:EE:FF","plan":"plan_200_100"}' \
  http://ROUTER-IP:8880/plan

{ "ok": true, "code": 200, "message": "Plan assigned", "mac": "AA:BB:CC:DD:EE:FF", "plan": "plan_200_100" }

404 para un cliente o plan desconocido.

POST /suspend

Modifica el router

Bloquea el tráfico del cliente (reglas de suspensión) hasta que se reanude.

La MAC puede ir en el cuerpo o en la ruta (POST /suspend/{mac}). Suspender manualmente borra el indicador de suspensión automática (por fecha de fin).

Nombre	En	Tipo	Notas
mac	body o path	string	Obligatorio.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mac":"AA:BB:CC:DD:EE:FF"}' http://ROUTER-IP:8880/suspend

{ "ok": true, "code": 200, "message": "Client suspended", "mac": "AA:BB:CC:DD:EE:FF", "suspended": true }

POST /resume

Modifica el router

Quita la suspensión del cliente.

Los mismos parámetros que POST /suspend (MAC en el cuerpo o en la ruta).

curl -X POST -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/resume/AA:BB:CC:DD:EE:FF

{ "ok": true, "code": 200, "message": "Client resumed", "mac": "AA:BB:CC:DD:EE:FF", "suspended": false }

POST /expires

Modifica el router

Establece la fecha de fin del cliente; una fecha pasada lo suspende de inmediato, una fecha posterior reanuda a un cliente que la fecha de fin había suspendido.

Una vez almacenada la fecha, las fechas de fin de todos los clientes se concilian de inmediato (el router también lo hace cada 5 minutos).

Nombre	En	Tipo	Notas
mac	body	string	Obligatorio.
expires	body	date	YYYY-MM-DD o YYYY-MM-DD HH:MM; vacío o never la borra.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"mac":"AA:BB:CC:DD:EE:FF","expires":"2026-10-31"}' \
  http://ROUTER-IP:8880/expires

{
  "ok": true,
  "code": 200,
  "message": "End date set",
  "mac": "AA:BB:CC:DD:EE:FF",
  "expires": "2026-10-31 00:00:00",
  "suspended": false
}

400 para una fecha que no puede interpretar, 404 para un cliente desconocido.

Equivalentes en la API de acciones

Todas son GET /api?action=… con los parámetros en la cadena de consulta (vea la descripción general de la API).

Acción	Parámetros de consulta	Equivale a
action=list	[network]	GET /clients
action=search	q	GET /clients?q= (la respuesta agrega query)
action=get	mac	GET /clients/{mac}
action=add	mac, ip, [hostname], [comment], [ipv6]	POST /clients (sin plan ni fecha de fin)
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