Servicios

Un servicio es un cliente en una ONT, con una velocidad, una dirección fija y un id permanente. Una sola llamada registra la ONT en su OLT (perfiles, límite de velocidad, service-port QinQ) y configura el lado del router: la interfaz VLAN del puerto, DHCP con Option 82, IPv6 y un prefijo delegado, CGNAT, contabilidad y anti-spoofing. Lea primero Conceptos para entender la numeración.

Antes del primer servicio

• La OLT está registrada con la S-VLAN de este router: dtvsol olt add … --svlan <n>. Consulte OLT.
• La interfaz de la S-VLAN vlan<svlan> existe en el puerto o bond que da hacia la OLT.
• Los pools de direcciones de los servicios están definidos en /opt/dtvsol/etc/config.php: svc_ipv4_pool (por ejemplo 100.64.0.0/10), y para IPv6 svc_ipv6_pool y svc_pd_pool. Sin un pool IPv6, los servicios son solo IPv4.

El flujo del técnico

1. El técnico conecta y enciende la ONU.

2. Lista las ONT que están conectadas y aún no registradas:

   dtvsol service unregistered

3. Elige el serial y crea el servicio:

   dtvsol service add 485754430A1B2C3D --name "Example Customer" --plan plan_200_200 \
       --olt olt-1 --pon 0/1/0 --ref C-0001 --contract C-0001

4. El comando imprime la VLAN que se debe configurar en la WAN de la ONU, con DHCP. Luego la ONU recibe su dirección fija.

Referencia de la CLI

dtvsol service unregistered [--olt n]
dtvsol service add <sn> --name "..." (--plan p | --down d --up u) [--olt n] [--pon f/s/p]
                  [--user-vlan v] [--ref r] [--contract c] [--expires YYYY-MM-DD|never]
                  [--comment ...] [--iptv] [--no-ipv6]
dtvsol service list [--state active|suspended|error] [--olt n] [-q text] [--fast] [--json]
dtvsol service get <id>
dtvsol service set <id> [--plan p | --down d --up u] [--name] [--contract] [--expires] [--comment] [--retry]
dtvsol service suspend <id> | resume <id>
dtvsol service del <id> [--keep-ont]
dtvsol service graph <id> [hour|day|week|month|year] [out.png] [--olt|--errors]

Notas:

• <id> puede ser el id del servicio, su ref, el serial de la ONT, el contrato, la dirección o la interfaz.
• --down/--up en lugar de --plan crea plan_<down>_<up> si no existe.
• --pon se puede omitir: el router busca el serial en la tabla autofind de la OLT.
• --user-vlan es para una ONU que ya envía otra VLAN (por ejemplo, al tomar una red existente). La OLT la traduce; la ONU no se toca.
• --ref hace que la llamada sea idempotente: el mismo ref devuelve el mismo servicio.
• --iptv pone el segundo puerto Ethernet de la ONT en la VLAN de IPTV de la OLT.
• Un cambio de plan pasa la ONT al nuevo límite de velocidad en la OLT. El cliente ve unos segundos de interrupción.
• Suspender desactiva la ONT en la OLT y bloquea la dirección en el router. Con una fecha de vencimiento (--expires), el router suspende por sí mismo en esa fecha y reactiva cuando usted envía una fecha posterior.
• service graph --olt muestra el tráfico de la ONT tal como lo cuenta la OLT; --errors, sus errores de fibra (BIP, FEC).

Un abonado cuya ONT fue aprovisionada a mano igual se puede registrar:

dtvsol service add none --svlan 1000 --pon 0/1/0 --ont-id 7 --name "Example Customer" --plan plan_100_50

La API

Las mismas operaciones están disponibles por HTTP en el puerto 8880. Cada solicitud lleva la clave de API en el encabezado X-API-Key. La red de quien llama debe estar en la lista de permitidos (dtvsol protect add).

Dé a cada llamada al menos 60 segundos. Crear un servicio ocupa una sesión de OLT (10–40 s), y puede esperar a que termine el trabajo propio del router con la OLT.

ONT no registradas:

curl -s -H "X-API-Key: $KEY" "http://XXX.XXX.XXX.10:8880/services/unregistered?olt=olt-1"

{ "ok": true, "count": 1,
  "onts": [ { "olt": "olt-1", "pon": "0/1/0", "sn": "485754430A1B2C3D",
              "vendor": "HWTC", "seen_at": "2026-09-25 10:12:03+00:00",
              "svlan": 1000, "cvlan": 116 } ],
  "errors": {} }

Crear un servicio:

curl -s -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  "http://XXX.XXX.XXX.10:8880/services" -d '{
    "ref": "C-0001", "sn": "485754430A1B2C3D", "olt": "olt-1", "pon": "0/1/0",
    "down_mbps": 200, "up_mbps": 200, "name": "Example Customer",
    "ipv6": true, "expires": "2026-12-31" }'

La respuesta (201) trae el servicio. Guarde service.id. Muestre technician.user_vlan al técnico:

{ "ok": true, "message": "Service created",
  "service": {
    "id": "svc_d320fcbd", "ref": "C-0001", "olt": "olt-1", "pon": "0/1/0", "ont_id": 7,
    "svlan": 1000, "cvlan": 116, "user_vlan": 116, "iface": "v1000.116",
    "ipv4": { "network": "100.64.16.0/24", "gateway": "100.64.16.1", "address": "100.64.16.9" },
    "ipv6": { "link": "XXXX:XXXX:0:116::/64", "pd": "XXXX:XXXX:1:1600::/56" },
    "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" } }

Otras llamadas:

Llamada	Qué hace
GET /services/{id}	el registro, más el estado en vivo: enlace, en línea, MAC vista, lease DHCP
POST /services/{id}	cambia plan (o down_mbps/up_mbps), name, contract, comment, expires, o {"retry": true}
POST /services/{id}/suspend, /resume	cortar y restablecer
DELETE /services/{id}	lo elimina en todas partes (?keep_ont=1 deja la ONT registrada)
GET /services/{id}/graph?period=day	un PNG del tráfico
GET /services?state=active&olt=olt-1&q=text&fast=1	la lista

Códigos de error que debe manejar: 400 campo incorrecto, 404 serial no está en autofind, 409 el serial ya pertenece a un servicio (la respuesta lo incluye), 502 la OLT rechazó la operación o no se pudo alcanzar (no se creó nada), 500 el lado de la OLT funcionó pero falló el lado del router (el servicio existe en estado error: corrija la causa y luego envíe {"retry": true}), 507 no quedan direcciones en ese puerto.

La guía completa de integración para los equipos de facturación está en Integración con el sistema de facturación.