API de servicios

Un servicio es un abonado en la red de fibra: una ONT en un puerto PON de una OLT registrada, una dirección IPv4 fija (y opcionalmente IPv6 con un prefijo delegado) en la red de ese puerto, un plan de velocidad y una fecha de fin opcional. Esta es la API que usa un sistema de facturación. No se necesita la dirección MAC del CPE: el router reconoce la ONT por el puerto y el id de ONT que la OLT agrega a sus solicitudes DHCP (Option 82).

La numeración se deriva, nunca se elige: los abonados de un puerto PON comparten la C-VLAN de ese puerto, 100 + card × 16 + pon (puerto 0/1/0 → C-VLAN 116) dentro de la S-VLAN del router, y su bloque de direcciones. Los registros heredados basados en MAC son la API de clientes.

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.

Tiempos de espera

Las llamadas que interactúan con una OLT (POST /services, cambios de plan, suspender/reanudar, eliminar, migrar, GET /services/unregistered) mantienen una sesión con la OLT: permita al menos 60 s por llamada. Un router se comunica con una OLT de a una sesión a la vez, por lo que una llamada puede tener que esperar primero a que termine el trabajo del propio router con la OLT.

El flujo de facturación

1. El técnico instala la ONU; el sistema de facturación consulta GET /services/unregistered y muestra los números de serie encontrados.
2. El técnico elige uno; el sistema de facturación llama a POST /services con su propio ref, el sn, olt, pon, el plan y el nombre.
3. La respuesta (201) incluye service.id — guárdelo — y technician.user_vlan: configure la WAN de la ONU en esa VLAN con DHCP.
4. Después, por id: cambie el plan o la fecha de fin (POST /services/{id}), suspenda/reanude, elimine, consulte el estado o el gráfico de tráfico.

Estados del servicio

provisioning (en creación), active, suspended, error (la parte de la OLT se completó pero la parte del router falló — corrija la causa y envíe {"retry": true}).

Lectura

GET /services

Lista los servicios (los eliminados nunca se listan), cada uno con un bloque live salvo que se indique fast=1. states cuenta todos los servicios por estado.

Nombre	En	Tipo	Notas
state	query	string	active, suspended, error, provisioning.
olt	query	string	Solo los servicios de esta OLT.
q	query	string	Búsqueda de texto sin distinguir mayúsculas y minúsculas en todo el registro.
fast	query	1	Omite la comprobación en vivo (enlace, vecino, concesión).

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/services?state=active&olt=olt-1&fast=1"

{
  "ok": true,
  "code": 200,
  "count": 1,
  "states": { "active": 340, "suspended": 12 },
  "services": [
    {
      "id": "svc_1a2b3c4d",
      "ref": "billing-000812",
      "name": "Customer name",
      "olt": "olt-1",
      "pon": "0/1/0",
      "ont_id": 7,
      "state": "active"
    }
  ]
}

GET /services/{id}

Un servicio con su estado en vivo y su plan. {id} acepta el id del servicio, el ref del sistema de facturación, el número de serie de la ONT, el contrato, la dirección IPv4 o el nombre de la interfaz.

Nombre	En	Tipo	Notas
id	path	string	Id, ref, número de serie, contrato, dirección o interfaz.

curl -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/services/svc_1a2b3c4d

{
  "ok": true,
  "code": 200,
  "service": {
    "id": "svc_1a2b3c4d",
    "ref": "billing-000812",
    "name": "Customer name",
    "contract": "C-00812",
    "comment": null,
    "olt": "olt-1",
    "pon": "0/1/0",
    "ont_id": 7,
    "sn": "0123456789ABCDEF",
    "svlan": 500,
    "cvlan": 116,
    "user_vlan": 116,
    "iface": "v500.116",
    "ipv4": { "network": "100.64.16.0/24", "gateway": "100.64.16.1", "address": "100.64.16.9" },
    "ipv6": { "link": "XXXX:XXXX:a:183::/64", "pd": "XXXX:XXXX:b:8300::/56" },
    "plan": "plan_200_200",
    "iptv": false,
    "expires": "2026-10-31 00:00:00",
    "state": "active",
    "created": "2026-09-25 10:30:00",
    "updated": "2026-09-25 10:30:00",
    "olt_service_ports": { "internet": 1234, "iptv": null },
    "live": {
      "iface_exists": true,
      "link": "up",
      "online": true,
      "mac": "AA:BB:CC:DD:EE:FF",
      "neigh_state": "REACHABLE",
      "lease": { "state": "active", "mac": "AA:BB:CC:DD:EE:FF", "ends": "2026/09/28 12:00:00", "hostname": null }
    }
  },
  "plan": { "name": "plan_200_200", "down_mbps": 200, "up_mbps": 200 }
}

404 cuando ningún servicio coincide. El gráfico de tráfico de un servicio es GET /services/{id}/graph — vea la API del sistema.

GET /services/unregistered

Consulta a cada OLT registrada (o a una) las ONT que ve conectadas y aún no registradas — la lista de selección del técnico. Se consulta a cada OLT por turno. errors indica las OLT que no se pudieron consultar; cvlan es la C-VLAN que usa el puerto de la ONT.

Nombre	En	Tipo	Notas
olt	query	string	Consulta solo esta OLT.

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

{
  "ok": true,
  "code": 200,
  "count": 1,
  "onts": [
    {
      "olt": "olt-1",
      "pon": "0/1/0",
      "sn": "0123456789ABCDEF",
      "vendor": "ABCD",
      "model": "ONT-MODEL",
      "software": null,
      "seen_at": "2026-09-25 10:12:03+00:00",
      "svlan": 500,
      "cvlan": 116
    }
  ],
  "errors": {},
  "next": "POST /services {ref, sn, olt, pon, plan|down_mbps+up_mbps, name, ...}"
}

Cambios

POST /services

Modifica el router y la OLT

Registra la ONT en la OLT (perfiles, límite de velocidad, service-port) y luego crea en el router la dirección, DHCP, CGNAT, la contabilización y el anti-spoofing.

Crea un servicio en una sola llamada síncrona; cuando responde 201 el servicio ya está activo. Con ref, la llamada es idempotente: repetirla devuelve el servicio existente (200, "existing": true) en lugar de crear un segundo.

Nombre	En	Tipo	Notas
ref	body	string	Recomendado: el id propio del sistema de facturación para este servicio.
sn	body	string	Número de serie de la ONT, 16 dígitos hexadecimales. Obligatorio con una OLT.
olt	body	string	Nombre de la OLT registrada; obligatorio cuando hay más de una OLT registrada.
pon	body	string	Puerto PON frame/slot/port. Si se omite, el número de serie se busca en la tabla autofind de la OLT.
plan	body	string	Nombre de un plan existente…
down_mbps, up_mbps	body	integer	…o las velocidades: el plan plan_<down>_<up> se crea si no existe.
name	body	string	Obligatorio: el cliente.
contract, comment	body	string	Texto libre.
user_vlan	body	integer	1–4094: la VLAN que envía la ONU, cuando no es la C-VLAN del puerto (la OLT la traduce).
ipv6	body	boolean	Predeterminado true cuando el router tiene configurado un pool IPv6 de servicios.
iptv	body	boolean	Coloca el puerto IPTV de la ONT en la VLAN IPTV de la OLT (cuando la OLT tiene una).
expires	body	date	Fecha de fin; el router suspende el servicio en esa fecha, y lo reanuda cuando se establece una fecha posterior. never la borra.
svlan, ont_id	body	integer	Solo con "olt": "none" (una ONT aprovisionada manualmente): obligatorios junto con pon.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"ref":"billing-000812","sn":"0123456789ABCDEF","olt":"olt-1","pon":"0/1/0",
       "down_mbps":200,"up_mbps":200,"name":"Customer name","contract":"C-00812",
       "expires":"2026-10-31"}' \
  http://ROUTER-IP:8880/services

{
  "ok": true,
  "code": 201,
  "message": "Service created",
  "service": {
    "id": "svc_1a2b3c4d",
    "ref": "billing-000812",
    "pon": "0/1/0",
    "ont_id": 7,
    "svlan": 500,
    "cvlan": 116,
    "user_vlan": 116,
    "iface": "v500.116",
    "ipv4": { "network": "100.64.16.0/24", "gateway": "100.64.16.1", "address": "100.64.16.9" },
    "plan": "plan_200_200",
    "state": "active"
  },
  "technician": {
    "user_vlan": 116,
    "note": "set the ONU's WAN to VLAN 116, DHCP; it receives 100.64.16.9"
  }
}

Código	Significado
200	Ya existe un servicio con este ref; se devuelve con "existing": true.
400	Falta un campo o no es válido (error indica cuál).
404	OLT o plan desconocido, o el número de serie no está en la tabla autofind de la OLT.
409	El número de serie (o el id de ONT de ese puerto) ya pertenece a un servicio — que se devuelve en service — o el puerto no se puede usar (error indica por qué).
502	La OLT rechazó la operación; olt_raw contiene las últimas líneas de su respuesta. No se creó nada en el router.
500	La parte de la OLT tuvo éxito y la parte del router falló: el servicio existe en estado error; reintente con POST /services/{id} {"retry": true}.
507	No quedan direcciones para esta ONT en su puerto.

POST /services/{id}

Modifica el router y la OLT

Actualiza el registro; un cambio de plan pasa la ONT a la nueva velocidad en la OLT (unos segundos de interrupción).

Modifica uno o más campos. PUT se acepta de la misma forma. El campo olt de la respuesta indica si la parte de la OLT de un cambio de plan tuvo éxito.

Nombre	En	Tipo	Notas
id	path	string	Id, ref, número de serie, contrato, dirección o interfaz.
plan o down_mbps + up_mbps	body	string / integer	Nuevo plan (se crea a partir de las velocidades si no existe).
name, contract, comment, ref	body	string	Nuevos valores.
expires	body	date	Nueva fecha de fin, o never.
retry	body	boolean	Vuelve a ejecutar la parte del router (después de un 500 al crear).

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"plan":"plan_300_300"}' http://ROUTER-IP:8880/services/svc_1a2b3c4d

{
  "ok": true,
  "code": 200,
  "message": "Service updated",
  "changed": ["plan"],
  "olt": "ONT moved to the new plan on the OLT",
  "service": { "id": "svc_1a2b3c4d", "plan": "plan_300_300", "state": "active" }
}

400 cuando no se indica nada que modificar; 404 para un servicio desconocido.

POST /services/{id}/suspend

Modifica el router y la OLT

Desactiva la ONT en la OLT y bloquea la dirección del abonado en el router.

El paso de la OLT se puede desactivar en la configuración del router, dejando solo el bloqueo del lado del router.

Nombre	En	Tipo	Notas
id	path	string	Id, ref, número de serie, contrato, dirección o interfaz.

curl -X POST -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/services/svc_1a2b3c4d/suspend

{
  "ok": true,
  "code": 200,
  "message": "Service suspended",
  "olt": "ONT deactivated on the OLT",
  "service": { "id": "svc_1a2b3c4d", "state": "suspended" }
}

502 cuando la parte del router se completó pero la OLT no respondió en consecuencia (la respuesta lo indica): reintente.

POST /services/{id}/resume

Modifica el router y la OLT

Activa la ONT en la OLT y levanta el bloqueo del lado del router.

Los mismos parámetros y respuestas que suspender ("message": "Service resumed", "olt": "ONT activated on the OLT").

curl -X POST -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/services/svc_1a2b3c4d/resume

DELETE /services/{id}

Modifica el router y la OLT

Elimina el servicio del router y, salvo que se indique keep_ont, la ONT y sus service-ports de la OLT.

El registro se elimina del router aunque falle el paso de la OLT (el campo olt de la respuesta lo indica). La interfaz del puerto se mantiene para los demás abonados que la usan.

Nombre	En	Tipo	Notas
id	path	string	Id, ref, número de serie, contrato, dirección o interfaz.
keep_ont	query o body	boolean	Deja la ONT registrada en la OLT.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/services/svc_1a2b3c4d?keep_ont=1"

{
  "ok": true,
  "code": 200,
  "message": "Service deleted",
  "olt": null,
  "service": { "id": "svc_1a2b3c4d", "name": "Customer name", "state": "active" }
}

POST /services/{id}/migrate

Modifica el router y la OLT

Pasa el servicio a la VLAN y al bloque de direcciones de su puerto PON: la dirección del abonado cambia.

Uso del operador al renumerar (no forma parte del flujo de facturación): pasa un servicio creado con una numeración anterior a la C-VLAN y la dirección de su puerto, recreando el service-port en la OLT sin tocar la ONU. El id se mantiene; la ONU toma la nueva dirección en su siguiente DHCP. La interfaz anterior por abonado se elimina cuando ya nada más la usa.

Nombre	En	Tipo	Notas
id	path	string	Id, ref, número de serie, contrato, dirección o interfaz.

curl -X POST -H "X-API-Key: YOUR_API_KEY" http://ROUTER-IP:8880/services/svc_1a2b3c4d/migrate

{
  "ok": true,
  "code": 200,
  "message": "Service moved to its PON port",
  "olt": "service-port recreated: user-vlan 116 -> S-VLAN 500 / C-VLAN 116",
  "service": { "id": "svc_1a2b3c4d", "iface": "v500.116", "state": "active" },
  "note": "the ONU keeps its settings; it takes the new address at its next DHCP (reboot the ONT to make that now)"
}

Responde "message": "Already on its port" (ya está en su puerto) cuando no hay nada que mover; 409 cuando el puerto, la dirección o la C-VLAN está ocupado por otra cosa; 502 cuando la OLT rechaza la operación (la parte del router no cambia).

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=service-list	[state], [olt], [q], [fast=1]	GET /services
action=service-get	id	GET /services/{id}
action=service-unregistered	[olt]	GET /services/unregistered
action=service-add	sn, olt, pon, plan o down_mbps+up_mbps, name, [ref], [contract], [ipv6], [iptv], [expires]	POST /services
action=service-set	id, [plan], [name], [expires], [retry=1] …	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-expiry	—	Ejecuta ahora la comprobación de fechas de fin (suspende lo vencido, reanuda lo extendido); responde {"changed": [...]}.