Integración OZmap x Alterpay

La integración de OZmap con Alterpay es de tipo pasiva, realizada mediante llamadas de API desde Alterpay para consumir recursos proporcionados por OZmap. A diferencia de las integraciones bidireccionales, aquí Alterpay no sustituye a OZmap como herramienta de documentación de red: OZmap continúa siendo la fuente de verdad, manteniendo el diseño GIS, postes, cables, cajas, splitters y diagramas de empalme, mientras que Alterpay únicamente consulta esta información para apoyar la venta, el precontrato, el aprovisionamiento, el monitoreo del servicio y la baja.

La integración contempla la consulta de factibilidad FTTH con reserva de puerto, la implementación y actualización de clientes/propiedades, la cancelación de clientes y reservas, la actualización de caja, splitter y puerto, y la consulta del vínculo con OZmap directamente desde el detalle del servicio.

Integración Alterpay → OZmap


Prácticamente todas las funcionalidades de la integración parten de Alterpay hacia OZmap. La única excepción es la consulta del vínculo, que obtiene datos de OZmap para mostrarlos en Alterpay.

Consulta de Factibilidad con Reserva de Puerto en OZmap


La consulta de factibilidad con reserva de puerto consiste en utilizar la red documentada en OZmap durante los procesos de venta, precontrato, aprovisionamiento u operación de campo en Alterpay, para verificar si existe factibilidad FTTH en una ubicación y reservar un puerto para la instalación.

La verificación de cobertura y la búsqueda de cajas cercanas no son funcionalidades separadas; ambas forman parte de la misma consulta de factibilidad por radio. Alterpay consulta OZmap utilizando:

  • Latitud
  • Longitud
  • Radio típico de 400 metros


El proceso ocurre de la siguiente manera:

  • El usuario informa o ajusta el punto de instalación en el mapa, en pantallas como ventas, precontrato, aprovisionamiento o cobertura de campo.
  • Alterpay consulta OZmap para verificar la factibilidad FTTH dentro del radio configurado.
  • Si existe factibilidad, Alterpay muestra las cajas OZmap cercanas dentro del radio de atención, ordenadas por distancia y mostrando la cantidad de puertos libres.
  • El usuario puede seleccionar una caja y revisar la cuadrícula de puertos del splitter o, cuando está habilitado, Alterpay puede seleccionar automáticamente la caja más cercana con al menos un puerto disponible.
  • Después de seleccionar un puerto libre, Alterpay puede reservar el puerto de la caja para la orden de trabajo mientras avanza el proceso de activación.


La consulta puede devolver tres resultados: hay cobertura (existen recursos FTTH viables dentro del radio), no hay cobertura (no se encontró ningún recurso viable) o error de consulta (la consulta falló y el mapa mantiene el último punto seleccionado para un nuevo intento). Si no existen cajas dentro del radio de búsqueda, Alterpay informa la ausencia de cajas disponibles, pero el flujo comercial puede continuar sin una caja seleccionada, y el vínculo puede completarse posteriormente desde el servicio.

Estados de los puertos en la selección


Solo los puertos libres pueden seleccionarse para nuevas activaciones:

  • Libre — puerto disponible para una nueva asignación; puede seleccionarse.
  • Ocupado en OZmap — el puerto ya aparece ocupado en la planta documentada; no puede seleccionarse.
  • Reservado por otra orden — otra orden de trabajo de Alterpay ya tiene una reserva en ese puerto; no puede seleccionarse.
  • Bloqueado — puerto no disponible para el flujo comercial; no puede seleccionarse.


Implementación y actualización de Clientes/Propiedades en OZmap


La implementación y actualización de clientes/propiedades consiste en crear o actualizar, desde Alterpay, el registro operativo asociado al servicio FTTH en OZmap durante el aprovisionamiento o la activación.

  • Durante el aprovisionamiento o la activación, Alterpay utiliza la caja y el puerto seleccionados anteriormente o permite completar esta selección durante el flujo operativo.
  • Alterpay crea o actualiza la propiedad en OZmap asociada al servicio FTTH.
  • Se sincronizan metadatos operativos del servicio, como nombre, etiquetas, estado de implementación, observaciones y cliente FTTH.
  • Si el aprovisionamiento se guarda como borrador, la caja, el puerto y los metadatos de la propiedad permanecen conservados para retomarlos posteriormente.


Esta funcionalidad mantiene el vínculo entre el proceso operativo de Alterpay y la documentación del cliente/propiedad en OZmap, sin modificar la responsabilidad de OZmap sobre la documentación de la red.

Cancelación de Clientes y Reservas en OZmap


La cancelación de clientes y reservas consiste en liberar al cliente o la propiedad relacionada con el servicio cuando ocurre una baja o cancelación en Alterpay.

  • El usuario accede al detalle del servicio en Alterpay.
  • En la pestaña OZmap, utiliza la opción "Eliminar de OZmap".
  • Alterpay solicita la liberación del cliente o propiedad correspondiente en OZmap.


A diferencia de una eliminación automática, desactivar el gateway de mapas en Alterpay no elimina las propiedades existentes en OZmap; la liberación debe realizarse explícitamente desde el flujo del servicio cuando corresponda.

Actualización de Caja, Splitter y Puerto de Clientes OZmap


La actualización de caja, splitter y/o puerto de clientes en OZmap consiste en modificar, desde Alterpay, la información del vínculo operativo del servicio cuando sea necesario ajustar la caja o el puerto utilizado por el cliente.

Esta funcionalidad puede utilizarse tanto en flujos de aprovisionamiento como en el detalle del servicio, manteniendo la relación entre el servicio de Alterpay y la estructura documentada en OZmap. Al modificar una caja o un puerto, Alterpay debe respetar los estados de disponibilidad devueltos por la integración, permitiendo seleccionar únicamente puertos con estado Libre.

Consulta del vínculo OZmap en el servicio (OZmap → Alterpay)


La consulta del vínculo permite visualizar, en Alterpay, los datos de la relación entre el servicio del cliente y OZmap. En la ruta Clientes → Servicio → OZmap, se pueden consultar:

  • Estado de la integración
  • Estado de implementación
  • Caja y puerto
  • Cliente FTTH
  • Datos de la propiedad

En la misma pestaña también es posible editar información relacionada con OZmap o liberar la relación del cliente con la integración.

Dónde se utiliza la integración en Alterpay

  • Ventas — ruta Comercial → Ventas → Crear → Mapa. Permite consultar la factibilidad FTTH, visualizar cajas cercanas dentro del radio de atención, seleccionar caja y puerto y revisar los estados de reserva.
  • Precontrato — ruta Leads → Precontrato → Ubicación en el mapa. Permite fijar el punto de instalación, editar latitud y longitud, consultar cajas OZmap dentro de 400 metros y visualizar puertos libres, reservados u ocupados. Si el módulo Mapas está desactivado, la tarjeta Caja OZmap simplemente no aparece y el resto del flujo de precontrato continúa funcionando normalmente.
  • Aprovisionamiento — ruta Operaciones → Aprovisionar. Permite seleccionar caja y puerto, mantener una reserva de puerto en la caja y registrar los metadatos de la propiedad (nombre, etiquetas, observaciones, estado de implementación). El aprovisionamiento puede guardarse como borrador en cualquier etapa, conservando estos datos para retomarlos posteriormente.
  • Detalle del servicio — ruta Clientes → Servicio → OZmap. Muestra el estado de la integración, el estado de implementación, la caja y el puerto, el cliente FTTH y los datos de la propiedad, además de permitir editar esta información o liberar al cliente/propiedad.
  • Aplicaciones de campo — vendedores e instaladores consultan la misma integración OZmap utilizada en el dashboard de Alterpay, manteniendo una única fuente de verdad para la cobertura, selección de caja y análisis del estado de los puertos (Vendedores → Cobertura y Precontrato; Instaladores → Cobertura).

Configuración de la integración


La configuración se realiza en Alterpay, en la ruta Configuración → Mapas:

  • Integración OZMap activa — habilita o pausa el uso de OZmap como Maps Gateway de la empresa; debe estar activa para consultar factibilidad, cajas y puertos.
  • API Key de OZmap — clave de autenticación del tenant de OZmap utilizada por Alterpay, obligatoria y almacenada de forma cifrada.
  • Subdominio de OZmap — subdominio de la instancia de OZmap del ISP, obligatorio para validar la conexión.
  • Radio de factibilidad — radio utilizado para consultar la factibilidad y las cajas cercanas, normalmente de 400 metros.

Para configurar, el usuario debe acceder a Configuración → Mapas, localizar la integración OZMap, activar el interruptor Activo, abrir Configuraciones (o "Configurar API / Claves"), ingresar la API Key y el subdominio de OZmap y hacer clic en Validar y guardar. Durante la validación, Alterpay prueba la conexión intentando listar los proyectos de OZmap.

La integración puede presentar los siguientes estados:

  • Pendiente — la integración aún no ha sido validada; las consultas de factibilidad y recursos pueden no estar disponibles.
  • READY / Listo — las credenciales fueron validadas correctamente; la integración está preparada para consultar factibilidad, cajas, puertos y sincronizar datos operativos.
  • Otros estados de gateway — indican un problema o una condición específica de conexión, por lo que es necesario revisar la configuración, las credenciales o la conectividad.

Si la integración está desactivada, las pantallas de cobertura pueden ocultarse o indicar ausencia de capacidad soportada, y no será posible consultar cajas o puertos. Sin embargo, las demás funcionalidades de Alterpay (cobros, portal, tickets) continúan funcionando normalmente.

Datos necesarios


Del lado de Alterpay:

  • Módulo Mapas habilitado — la empresa debe contar con el módulo Mapas disponible para utilizar OZmap como gateway.
  • Permiso de configuración — el usuario debe tener permisos para configurar integraciones en Alterpay (administrador u operador autorizado).

Del lado de OZmap:

  • API Key: clave de autenticación del usuario/tenant de OZmap utilizada por Alterpay para enviar solicitudes mediante API.
  • Subdominio: subdominio de la instancia de OZmap del ISP (ej.: cliente.ozmap.com.br).
  • Cuenta OZmap activa: el tenant debe estar operativo y contar con proyectos disponibles para la validación.


La documentación de Alterpay no detalla una política específica de liberación de IP para esta integración. Si el entorno del cliente utiliza restricciones de red, se recomienda validar directamente con los equipos responsables de Alterpay y OZmap si es necesaria alguna liberación adicional para el tráfico de salida o entrada.


Problemas comunes


La integración no aparece

  • Verificar si el usuario cuenta con permisos de configuración.
  • Verificar si la empresa tiene habilitado el módulo Mapas.
  • Verificar si la integración OZMap está registrada como Maps Gateway.

La factibilidad no está disponible

  • Verificar si el interruptor Activo está habilitado.
  • Verificar si la API Key es válida.
  • Verificar si el subdominio es correcto.
  • Verificar si el estado de la integración es READY / Listo.

La tarjeta Caja OZmap no aparece

  • Mapas está desactivado.
  • Las credenciales no fueron validadas.
  • La empresa no tiene habilitada la verificación de factibilidad.

No hay cajas cercanas

  • La búsqueda utiliza un radio de 400 metros; si no existen cajas dentro de este radio, el flujo puede continuar sin una caja y el vínculo podrá realizarse posteriormente desde el servicio.
  • Recomendación: no se debe prometer una instalación sin confirmar la factibilidad operativa real, aunque el flujo comercial pueda continuar sin una caja asignada.

La consulta de factibilidad falla

  • Utilizar la opción "Intentar nuevamente"; el mapa mantiene el último punto seleccionado.
  • Si el problema persiste, revisar: estado de OZmap, API Key, subdominio, conectividad y estado de la integración en Alterpay.