Integración con el sistema de facturación

Un sistema de facturación (billing) puede controlar el router de dos maneras:

• La API REST en el puerto 8880. Las integraciones nuevas la usan, con servicios.
• MK-api en el puerto 8728: un receptor de la API de MikroTik RouterOS, para un billing que ya aprovisiona routers MikroTik y no se puede modificar. Funciona con clientes basados en MAC.

Conceptos básicos de la API REST

• Dirección: http://<router>:8880.

• Cada solicitud lleva la clave de API: encabezado X-API-Key: <key> (o ?api_key= en GET). La clave fue impresa por el instalador y está en /opt/dtvsol/etc/config.php.

• La red del servidor de billing debe estar en la lista de permitidos (allow-list):

  dtvsol protect add XXX.XXX.XXX.25 "billing"

• Entra JSON, sale JSON.

• Tiempos de espera: al menos 60 segundos por llamada (120 s es holgado). Crear un servicio ocupa una sesión de OLT (10–40 s), y el router habla con una OLT una sesión a la vez. Una llamada que llega mientras el router está sincronizando o guardando esa OLT espera hasta unos 25 s más. Eso no es un error: no reintente antes de tiempo.

El flujo de aprovisionamiento

 billing (support)       billing (technician app)          router                    OLT
 1. create customer
    and contract
                         2. installs the ONU, taps
                            "register ONU"
                            GET /services/unregistered --> asks every OLT ------->  autofind
                            <-- list of ONTs {olt, pon, sn, vendor}
                         3. picks the serial
                            POST /services ------------->  registers the ONT --->  ONT, service-port,
                            {ref, sn, olt, pon, plan}      address, DHCP, CGNAT,   rate limit
                                                           anti-spoofing
                            <-- 201 {service: {id, ipv4}, technician: {user_vlan}}
                         4. shows "ONU WAN = VLAN <user_vlan>, DHCP"
 5. stores service.id
 6. later, by id: plan change, suspend/resume, end date, delete, status, graph

Endpoints

Llamada	Propósito
GET /services/unregistered[?olt=<name>]	ONT conectadas y no registradas (unos 3 s por OLT)
POST /services	crear un servicio (la llamada única)
GET /services/{id}	estado: registro, plan y estado en vivo
POST /services/{id}	cambiar plan, nombres, fecha de fin, o reintentar
POST /services/{id}/suspend, /resume	cortar en la fibra y en el router, y restablecer
DELETE /services/{id}[?keep_ont=1]	eliminarlo; el id nunca se reutiliza
GET /services/{id}/graph?period=hour|day|week|month|year	un PNG del tráfico
GET /services?state=…&olt=…&q=…&fast=1	listar; fast=1 omite la consulta en vivo

{id} acepta el id del servicio, su ref, el serial, el contrato o la dirección IPv4.

Campos de POST /services

Campo	Obligatorio	Significado
ref	recomendado	su id para este servicio. Hace que la llamada sea idempotente: repetirla devuelve el servicio existente (200, existing: true).
sn	sí	el serial de la ONT, 16 dígitos hexadecimales
olt	cuando hay más de una OLT	el nombre de la OLT
pon	recomendado	frame/slot/port; se busca en autofind si se omite
plan, o down_mbps + up_mbps	sí	un nombre de plan, o velocidades (se crea plan_<down>_<up> si no existe)
name	sí	el cliente, como usted quiera verlo en el router
contract, comment	no	texto libre, guardado y consultable
user_vlan	no	la VLAN que envía la ONU, cuando no es la del puerto
ipv6	no	por defecto true cuando el router tiene un pool IPv6
iptv	no	el segundo puerto Ethernet de la ONT en la VLAN de IPTV
expires	no	fecha de fin: se suspende en esa fecha y se reanuda cuando usted envía una posterior

Ejemplo de solicitud:

{ "ref": "C-0001", "sn": "485754430A1B2C3D", "olt": "olt-1", "pon": "0/1/0",
  "down_mbps": 200, "up_mbps": 200, "name": "Example Customer",
  "contract": "C-0001", "ipv6": true, "expires": "2026-12-31" }

Guarde service.id de la respuesta, y muestre technician.user_vlan al técnico. La dirección del abonado (service.ipv4.address) es fija durante toda la vida del servicio. Vea Servicios para una respuesta completa.

Cambios

{ "plan": "plan_300_300" }
{ "down_mbps": 300, "up_mbps": 300 }
{ "name": "…", "contract": "…", "comment": "…", "ref": "…" }
{ "expires": "2026-11-30" }
{ "expires": "never" }
{ "retry": true }

Un cambio de plan mueve la ONT al nuevo límite de velocidad (unos segundos de interrupción). El campo olt de la respuesta indica si el lado de la OLT tuvo éxito. Un 502 al suspender o reanudar significa que el lado del router se completó y la OLT no lo siguió: reintente.

Errores

Código	Significado	Qué hacer
400	falta un campo o no es válido (error indica cuál)	corrija la solicitud
404	el serial no está en la tabla de autofind de la OLT	la ONU no está conectada, aún no se ha visto, o ya está registrada
409	el serial ya pertenece a un servicio (se devuelve), o el puerto no se puede usar ahora	use el id devuelto; de lo contrario, consulte al operador
502	la OLT rechazó la operación o no se pudo alcanzar	reintente más tarde; no se creó nada
500	el lado de la OLT funcionó, el lado del router falló	el servicio queda en estado error: {"retry": true} después de corregir la causa
507	no quedan direcciones en ese puerto	consulte al operador

Notas

• Envíe siempre ref. Así, un reintento después de un tiempo de espera de red nunca crea un segundo servicio.
• La numeración se deriva, nunca se elige. Vea Conceptos.
• La dirección MAC no es un dato de entrada. Si el cliente reemplaza su router, el servicio sigue funcionando con la misma dirección y el mismo id.

MK-api (compatible con MikroTik)

MK-api escucha en TCP 8728 y habla lo suficiente de la API de MikroTik RouterOS como para que un billing crea que está hablando con un MikroTik. Convierte los comandos del billing en llamadas a la API propia del router.

Alcance: solo DHCP/IPoE.

Comando del billing	Qué hace el router
/ip/dhcp-server/lease/add	crea un cliente (MAC + dirección)
/ip/dhcp-server/lease/set (disabled)	suspende o reanuda el cliente
/ip/dhcp-server/lease/remove	elimina el cliente
/ip/dhcp-server/lease/print	lista los clientes
/queue/simple/… o un rate-limit de un lease	fija la velocidad: se crea para ello un plan mk_<down>m_<up>m
/ppp/… (PPPoE)	rechazado

Configúrelo:

dtvsol mkapi                                          # status
dtvsol mkapi set user billing password '<password>'
dtvsol mkapi set identity router-1

identity, model <m> y version <v> fijan lo que responde el router cuando el billing pregunta con qué MikroTik está hablando. port <n> cambia el puerto.

Precaución

El instalador guarda una contraseña provisional. Configure la suya antes de conectar un billing.

La dirección del billing debe estar en la lista de permitidos (dtvsol protect add). El receptor se ejecuta como dtvsol-mkapi.service.