Integração OZmap x Alterpay

A integração do OZmap com o Alterpay é do tipo passiva, feita por chamadas de API partindo do Alterpay para consumir recursos disponibilizados pelo OZmap. Diferente de integrações bidirecionais, aqui o Alterpay não substitui o OZmap como ferramenta de documentação de rede: o OZmap continua sendo a fonte de verdade, mantendo o desenho GIS, postes, cabos, caixas, splitters e diagramas de emenda, enquanto o Alterpay apenas consulta essas informações para apoiar venda, pré-contrato, provisionamento, monitoramento do serviço e baixa.

A integração prevê consulta de viabilidade FTTH com reserva de porta, implantação e atualização de clientes/propriedades, cancelamento de clientes e reservas, atualização de caixa, splitter e porta e consulta do vínculo OZmap diretamente no detalhe do serviço.

Integração Alterpay -> OZmap

Praticamente todas as funcionalidades da integração partem do Alterpay em direção ao OZmap. A única exceção é a consulta do vínculo, que traz dados do OZmap de volta para exibição no Alterpay.

Consulta de Viabilidade com Reserva de Porta no OZmap

A consulta de viabilidade com reserva de porta consiste em utilizar a rede documentada no OZmap durante os processos de venda, pré-contrato, provisionamento ou operação de campo no Alterpay, para verificar se há viabilidade FTTH em uma localização e reservar uma porta para a instalação.

A verificação de cobertura e a busca de caixas próximas não são funcionalidades separadas — ambas fazem parte da mesma consulta de viabilidade por raio. O Alterpay consulta o OZmap utilizando:

• Latitude
• Longitude
• Raio típico de 400 metros

O processo ocorre da seguinte forma:

• O usuário informa ou ajusta o ponto de instalação no mapa, em telas como vendas, pré-contrato, provisionamento ou cobertura de campo.
• O Alterpay consulta o OZmap para verificar a viabilidade FTTH dentro do raio configurado.
• Havendo viabilidade, o Alterpay apresenta as caixas OZmap próximas dentro do raio de atendimento, ordenadas por distância e exibindo a quantidade de portas livres.
• O usuário pode selecionar uma caixa e revisar a grade de portas do splitter, ou, quando habilitado, o Alterpay pode selecionar automaticamente a caixa mais próxima com ao menos uma porta disponível.
• Após a seleção de uma porta livre, o Alterpay pode reservar a porta da caixa para a ordem de trabalho enquanto o processo de ativação avança.

A consulta pode retornar três resultados: há cobertura (existem recursos FTTH viáveis dentro do raio), não há cobertura (nenhum recurso viável foi encontrado) ou erro de consulta (a consulta falhou e o mapa mantém o último ponto selecionado para nova tentativa). Se não existirem caixas dentro do raio de busca, o Alterpay informa a ausência de caixas disponíveis, mas o fluxo comercial pode continuar sem caixa selecionada, sendo o vínculo concluído posteriormente a partir do serviço.

Estados de portas na seleção

Somente portas livres podem ser selecionadas para novas ativações:

• Livre — porta disponível para uma nova atribuição; pode ser selecionada.
• Ocupada no OZmap — a porta já aparece ocupada na planta documentada; não pode ser selecionada.
• Reservada por outra ordem — outra ordem de trabalho do Alterpay já possui reserva nessa porta; não pode ser selecionada.
• Bloqueada — porta indisponível para o fluxo comercial; não pode ser selecionada.

Implantação e atualização de Clientes/Propriedades no OZmap

A implantação e atualização de clientes/propriedades consiste em criar ou atualizar, a partir do Alterpay, o registro operacional associado ao serviço FTTH no OZmap durante o provisionamento ou a ativação.

• Durante o provisionamento ou a ativação, o Alterpay utiliza a caixa e a porta selecionadas anteriormente, ou permite completar essa seleção no fluxo operacional.
• O Alterpay cria ou atualiza a propriedade no OZmap associada ao serviço FTTH.
• São sincronizados metadados operacionais do serviço, como nome, etiquetas, estado de implantação, observações e cliente FTTH.
• Se o provisionamento for salvo como rascunho, a caixa, a porta e os metadados da propriedade permanecem preservados para retomada posterior.

Essa funcionalidade mantém o vínculo entre o processo operacional do Alterpay e a documentação do cliente/propriedade no OZmap, sem alterar a responsabilidade do OZmap sobre a documentação da rede.

Cancelamento de Clientes e Reservas no OZmap

O cancelamento de clientes e reservas consiste em liberar o cliente ou a propriedade relacionada ao serviço quando ocorre baixa ou cancelamento no Alterpay.

• O usuário acessa o detalhe do serviço no Alterpay.
• Na aba OZmap, utiliza a opção "Eliminar de OZmap".
• O Alterpay solicita a liberação do cliente ou propriedade correspondente no OZmap.

Diferente de uma exclusão automática, desativar o gateway de mapas no Alterpay não remove as propriedades existentes no OZmap — a liberação precisa ser feita explicitamente no fluxo do serviço quando aplicável.

Atualização de Caixa, Splitter e Porta de Clientes OZmap

A atualização de caixa, splitter e/ou porta de clientes no OZmap consiste em alterar, a partir do Alterpay, as informações de vínculo operacional do serviço sempre que for necessário ajustar a caixa ou a porta utilizada pelo cliente.

Essa funcionalidade pode ser usada tanto em fluxos de provisionamento quanto no detalhe do serviço, mantendo a relação entre o serviço do Alterpay e a estrutura documentada no OZmap. Ao alterar caixa ou porta, o Alterpay deve respeitar os estados de disponibilidade retornados pela integração, permitindo seleção apenas de portas com estado Livre.

Consulta do vínculo OZmap no serviço (OZmap -> Alterpay)

A consulta do vínculo permite visualizar, no Alterpay, os dados do relacionamento entre o serviço do cliente e o OZmap. Na rota Clientes → Serviço → OZmap, podem ser consultados:

• Estado da integração
• Estado de implantação
• Caixa e porta
• Cliente FTTH
• Dados da propriedade

Na mesma aba também é possível editar informações relacionadas ao OZmap ou liberar a relação do cliente com a integração.

Onde a integração é utilizada no Alterpay

• Vendas — rota Comercial → Vendas → Criar → Mapa. Permite consultar viabilidade FTTH, visualizar caixas próximas dentro do raio de atendimento, selecionar caixa e porta e revisar estados de reserva.
• Pré-contrato — rota Leads → Pré-contrato → Localização no mapa. Permite fixar o ponto de instalação, editar latitude e longitude, consultar caixas OZmap dentro de 400 metros e visualizar portas livres, reservadas ou ocupadas. Se o módulo Mapas estiver desativado, o cartão Caixa OZmap simplesmente não aparece, e o restante do fluxo de pré-contrato continua funcionando normalmente.
• Provisionamento — rota Operações → Provisionar. Permite selecionar caixa e porta, manter uma reserva de porta em caixa e registrar os metadados da propriedade (nome, etiquetas, observações, estado de implantação). O provisionamento pode ser salvo como rascunho em qualquer etapa, preservando esses dados para retomada posterior.
• Detalhe do serviço — rota Clientes → Serviço → OZmap. Exibe o estado da integração, o estado de implantação, a caixa e porta, o cliente FTTH e os dados da propriedade, além de permitir editar essas informações ou liberar o cliente/propriedade.
• Aplicações de campo — vendedores e instaladores consultam a mesma integração OZmap utilizada no dashboard do Alterpay, mantendo uma única fonte de verdade para cobertura, seleção de caixa e análise do estado das portas (Vendedores → Cobertura e Pré-contrato; Instaladores → Cobertura).

Configuração da integração

A configuração é feita no Alterpay, na rota Configuração → Mapas:

• Integração OZMap ativa — habilita ou pausa o uso do OZmap como Maps Gateway da empresa; precisa estar ativa para consultar viabilidade, caixas e portas.
• API Key do OZmap — chave de autenticação do tenant OZmap utilizada pelo Alterpay, obrigatória e armazenada cifrada.
• Subdomínio do OZmap — subdomínio da instância OZmap do ISP, obrigatório para validar a conexão.
• Raio de viabilidade — raio utilizado para consultar viabilidade e caixas próximas, tipicamente 400 metros.

Para configurar, o usuário deve acessar Configuração → Mapas, localizar a integração OZMap, ativar o switch Ativo, abrir Configurações (ou "Configurar API / Chaves"), informar a API Key e o subdomínio do OZmap, e clicar em Validar e salvar. Durante a validação, o Alterpay testa a conexão tentando listar os projetos do OZmap.

A integração pode assumir os seguintes estados:

• Pendente — a integração ainda não foi validada; as consultas de viabilidade e recursos podem não estar disponíveis.
• READY / Pronto — as credenciais foram validadas corretamente; a integração está apta para consultar viabilidade, caixas, portas e sincronizar dados operacionais.
• Outros estados de gateway — indicam problema ou condição específica de conexão, sendo necessário revisar configuração, credenciais ou conectividade.

Se a integração estiver desativada, as telas de cobertura podem ser ocultadas ou indicar ausência de capacidade suportada, e não será possível consultar caixas ou portas — mas as demais funcionalidades do Alterpay (cobranças, portal, tickets) continuam funcionando normalmente.

Dados necessários

Do lado do Alterpay:

• Módulo Mapas habilitado — a empresa precisa possuir o módulo Mapas disponível para usar o OZmap como gateway.
• Permissão de configuração — o usuário precisa ter permissão para configurar integrações no Alterpay (administrador ou operador autorizado).

Do lado do OZmap:

• API Key: chave de autenticação do usuário/tenant OZmap utilizada pelo Alterpay para enviar requisições API.
• Subdomínio: subdomínio da instância OZmap do ISP (ex.: cliente.ozmap.com.br).
• Conta OZmap ativa: o tenant precisa estar operacional e possuir projetos disponíveis para validação.

A documentação do Alterpay não detalha uma política específica de liberação de IPs para esta integração. Caso o ambiente do cliente utilize restrições de rede, recomenda-se validar diretamente com as equipes responsáveis de Alterpay e OZmap se há necessidade de liberação adicional para tráfego de saída ou entrada.

Problemas comuns

A integração não aparece

• Verificar se o usuário possui permissões de configuração.
• Verificar se a empresa possui o módulo Mapas habilitado.
• Verificar se a integração OZMap está registrada como Maps Gateway.

A viabilidade não está disponível

• Verificar se o switch Ativo está habilitado.
• Verificar se a API Key é válida.
• Verificar se o subdomínio está correto.
• Verificar se o estado da integração é READY / Pronto.

O cartão Caixa OZmap não aparece

• Mapas está desativado.
• As credenciais não foram validadas.
• A empresa não possui verificação de viabilidade habilitada.

Não há caixas próximas

• A busca utiliza um raio de 400 metros; se não houver caixas dentro desse raio, o fluxo pode continuar sem caixa e o vínculo poderá ser feito posteriormente a partir do serviço.
• Recomendação: não se deve prometer uma instalação sem confirmar a viabilidade operacional real, mesmo que o fluxo comercial possa seguir sem caixa atribuída.

A consulta de viabilidade falha

• Utilizar a opção "Tentar novamente" — o mapa mantém o último ponto selecionado.
• Se o problema persistir, revisar: estado do OZmap, API Key, subdomínio, conectividade e estado da integração no Alterpay.