Integrator's Guide

Process summary

In general, the recommendation when starting the integration process with OZmap is to contact our integration team, who will assist with any questions related to the OZmap API and provide access to the OZmap Sandbox for testing.

It is also recommended to review the OZmap API documentation to become familiar with its operation and define the integration features according to the instructions provided in this document.

OZmap Integration Team

The official contact with the integration team is made through the email address integracoes@ozmap.com.br. From this initial contact, we will arrange the creation of a WhatsApp group to expedite communications regarding the new integration.

Access to the OZmap Sandbox

When contacting the OZmap integration team, we can provide the credentials for accessing the OZmap Sandbox. In this environment, users are created with access to both the interface and the API.

Recommended Features

Below, we present a series of recommended features, ranging from basic to advanced, segmented according to the type of software you wish to integrate with OZmap. For a better understanding of some features, we would like to highlight that OZmap works with two types of elements that compose a client: the client element (which represents the person who contracted the service) and the property element (which represents the client’s residence, where the physical installation of the internet occurs). Therefore, in OZmap, a customer is generally represented as a combination of the customer element + property element.

Business Management (ERP)

• Basic Features

  • Technical Feasibility - Perform a query in OZmap by providing the coordinates of a potential new customer to receive a list of boxes or condominiums with available ports to serve them at that location. To conduct feasibility by searching for boxes and condominiums, two requests are required: Feasibility by Radius (or Pole) and Condominium Feasibility.

    • API for feasibility by radius: https://ozmap.stoplight.io/docs/ozmap/8ffbbff600cd5-viabilidade-por-raio;

    • API for condominium feasibility: https://ozmap.stoplight.io/docs/ozmap/05378a036dcc2-viabilidade-de-condominios;

    • API usage description Feasibility;

  • Port Reservation - Create a property with an uninstalled customer in OZmap, representing a customer who has not yet been installed, and reserve a port for when they are activated.

    • API for creating customers: https://ozmap.stoplight.io/docs/ozmap/180b1534fb63f-cria-um-imovel;

    • API usage description Port reservation;

  • Customer Deployment - Update the deployment status of a customer from port reservation to “deployed,” converting the port reservation into an activated final customer once their installation is complete.

    • API for customer deployment: https://ozmap.stoplight.io/docs/ozmap/934d26a9b4202-atualiza-um-cliente;

    • API usage description Implantation/Client activation;

  • Removal of Reservations and Customers - Delete a port reservation customer or an active customer from OZmap after cancellation of installation or contract in the integrating system.

    • API for cancellation of reservations and customers: https://ozmap.stoplight.io/docs/ozmap/86688c5b178ac-exclui-um-cliente;

    • API usage description Cancel a Client/Reservation;

  • Address Change - Perform technical feasibility and port reservation for a customer’s new address who has requested a change of address. After the customer is activated at the new address, the OZmap customer at the old address is removed, and the new address customer is deployed. This process involves executing the Technical Feasibility, Port Reservation, and Customer Deployment (new address) functionalities and the Cancellation of Reservations and Customers (old address).

  • Update Customer Box - Update the customer’s box in OZmap for situations where the box used at the time of installation differs from the box where the customer’s port reservation was made. A new feasibility check is required to find the data for the new box to be assigned to the customer.

    • API for updating customer box: https://ozmap.stoplight.io/docs/ozmap/bad552b7cc42c-atualiza-um-imovel;

• Advanced Features

  • Search for Splitter, Box, and Port - Search OZmap for the customer’s connection data: the box, splitter, and port where they are currently connected. To do this, search for the customer’s property in OZmap, including the parameter populate=box.

    • API for searching customer connection data: https://ozmap.stoplight.io/docs/ozmap/587e8a06c9f36-lista-os-imoveis;

  • OZloc Module for Feasibility and Port Reservation - Use the OZloc module to perform feasibility and port reservations in a simple manner, both by coordinates and by text address, considering all available network elements for the customer’s network connection in OZmap, and utilizing different feasibility methods according to OZmap configurations, without the need for API requests. It can be initiated by inserting customer data via a URL parameter or via iframe to obtain the reservation data created in OZmap as a return.

    • OZloc usage description OZloc - English ver.

  • Update Customer Data in OZmap - Update general customer data in OZmap, such as name, address, notes, coordinates, etc. Since OZmap works with customer and property concepts, some information is updated in the customer element, and other information in the property element.

    • API for updating data in the customer element: https://ozmap.stoplight.io/docs/ozmap/934d26a9b4202-atualiza-um-cliente;

    • API for updating data in the property element: https://ozmap.stoplight.io/docs/ozmap/bad552b7cc42c-atualiza-um-imovel;

  • Update Customer Status - Update the status of customers in OZmap according to their current connection state (online or offline, for example). The available statuses are OK (green customer icon on the map) or ERROR (red icon). This is mainly used for identifying individual and/or general issues with customers in OZmap.

    • API for updating customer status: https://ozmap.stoplight.io/docs/ozmap/934d26a9b4202-atualiza-um-cliente;

    • API usage description Reading and updating a client status;

  • Update Customer Optical Power - Update the current optical signal power (in dBm) of customers in OZmap.

    • API for updating customer power:https://ozmap.stoplight.io/docs/ozmap/bad552b7cc42c-atualiza-um-imovel;

    • API usage description: Reading and updating the power at a client;

  • Create Pendencies - Create pendencies in OZmap to represent network or customer adjustments and corrections.

    • API for creating pendencies: https://ozmap.stoplight.io/docs/ozmap/386d7cc17b6f0-cria-uma-pendencia;

Monitoring/Provisioning

• Basic Features

  • Client Status Update - Update the status of customers in OZmap according to their current connection state (online or offline, for example). The available statuses are OK (green customer icon on the map) or ERROR (red icon). This is primarily used for identifying individual or general customer issues in OZmap.

    • API for updating customer status: https://ozmap.stoplight.io/docs/ozmap/934d26a9b4202-atualiza-um-cliente;

    • API usage description: Reading and updating a client status;

  • Update Customer Optical Power - Update customers' current optical signal power (in dBm) in OZmap.

    • API for updating customer power:https://ozmap.stoplight.io/docs/ozmap/bad552b7cc42c-atualiza-um-imovel;

    • API usage description: Reading and updating the power at a client;

• Advanced Features

  • ONU Data Update - Update the ONU data for a customer in OZmap, including MAC address, PPPoE user, and serial number.

    • API for updating ONU data: https://ozmap.stoplight.io/docs/ozmap/934d26a9b4202-atualiza-um-cliente;

  • PON Port Power Update for OLTs - Update the output power of PON ports on OLTs (optical signal, in dBm) in OZmap to improve the accuracy of the calculated power by project in OZmap network elements.

    • API usage description: Reading and updating launch power at PON ports in an OLT;

  • Comparison of Read Power vs. Calculated Power for Customers - Retrieve the calculated power by project within OZmap and compare it with the customer’s read power, potentially preventing provisioning if the read power is 2 dB worse than the calculated power in OZmap, for example.

    • API for retrieving customer read power: https://ozmap.stoplight.io/docs/ozmap/ca6844631241a-dados-do-imovel-codigo-do-cliente;

    • API for retrieving calculated power: https://ozmap.stoplight.io/docs/ozmap/173ab8b6726f6-imovel-olt-pop-codigo-do-cliente;

  • CTOs, Splitters, and Ports Availability for Provisioning - Search OZmap for a given location to find available CTOs, splitters, and ports for provisioning a customer. This involves performing feasibility checks, searching for splitters in the chosen box, and verifying which ports are available (output attribute).

    • API for searching boxes by location:https://ozmap.stoplight.io/docs/ozmap/8ffbbff600cd5-viabilidade-por-raio;

    • API for searching splitters by box: https://ozmap.stoplight.io/docs/ozmap/8337d3f9dc1c6-lista-os-splitters;

  • Customer Creation - Create customers in OZmap for each new ONU provisioned in the integrating system, for example.

    • API for customer creation: https://ozmap.stoplight.io/docs/ozmap/180b1534fb63f-cria-um-imovel;

  • Update Customer Data in OZmap - Update general customer data in OZmap according to information used for provisioning, such as box, port, splitter, coordinates, etc. Since OZmap works with customer and property concepts, some information is updated in the customer element, and other information in the property element.

    • API for updating data in the customer element: https://ozmap.stoplight.io/docs/ozmap/934d26a9b4202-atualiza-um-cliente;

    • API for updating data in the property element: https://ozmap.stoplight.io/docs/ozmap/bad552b7cc42c-atualiza-um-imovel;

  • Customer Deployment - Update the deployment status of a customer from port reservation to “deployed,” turning the port reservation into an activated final customer after ONU provisioning, for example.

    • API for customer deployment: https://ozmap.stoplight.io/docs/ozmap/934d26a9b4202-atualiza-um-cliente;

    • API usage description: Implantation/Client activation;

  • Customer Cancellation - Delete a customer from OZmap after ONU deprovisioning, for example.

    • API for customer cancellation: https://ozmap.stoplight.io/docs/ozmap/86688c5b178ac-exclui-um-cliente;

    • API usage description: Cancel a Client/Reservation;

Consultative Sales / Provider Query

• Basic features

  • Technical Feasibility – Perform a query in OZmap by inputting the coordinates of a potential new client to receive a list of distribution boxes or buildings with available ports to serve the client at this location. To assess feasibility by searching for boxes and buildings, two requests are needed: Feasibility by radius (or pole) and Feasibility of buildings.

    • API used for feasibility by radius: https://ozmap.stoplight.io/docs/ozmap/8ffbbff600cd5-viabilidade-por-raio

    • API used for building feasibility: https://ozmap.stoplight.io/docs/ozmap/05378a036dcc2-viabilidade-de-condominios

    • API usage description in OZmap: Feasibility

• Advanced Features

  • Port Reservation – Create a property for a client not implanted in OZmap, representing a client who has not been activated and reserving a port for future activation.

    • API used for client creation: https://ozmap.stoplight.io/docs/ozmap/180b1534fb63f-create-a-property

    • API usage description in OZmap: Port reservation

  • Prospect Creation – Create a prospect in OZmap to record clients who requested internet service but currently lack technical feasibility at their location.

    • API used for prospect creation: https://ozmap.stoplight.io/docs/ozmap/eeaee17d5416c-create-a-prospect

Chatbot / IVR

• Basic features

  • Technical Feasibility – Perform a query in OZmap by inputting the coordinates of a potential new client to receive a list of distribution boxes or buildings with available ports to serve the client at this location. To assess feasibility by searching for boxes and buildings, two requests are needed: Feasibility by radius (or pole) and Feasibility of buildings.

    • API used for feasibility by radius: https://ozmap.stoplight.io/docs/ozmap/8ffbbff600cd5-viabilidade-por-raio

    • API used for building feasibility: https://ozmap.stoplight.io/docs/ozmap/05378a036dcc2-viabilidade-de-condominios

    • API usage description in OZmap: Feasibility

• Advanced Features

  • Port Reservation – Create a property for a client not yet installed in OZmap, representing a client who has not been activated, reserving a port for future activation.

    • API used for client creation: https://ozmap.stoplight.io/docs/ozmap/180b1534fb63f-cria-um-imovel

    • API usage description in OZmap: Port reservation

  • Tag Query – Tag queries in OZmap can be used in various contexts. For example, in an IVR system, they can identify whether a client contacting support is in an area with a mass outage, allowing an appropriate notification about the issue.

    • API usage description in OZmap: Massive Outages

  • Prospect Creation – Create a prospect in OZmap to record clients who requested internet service but currently lack technical feasibility at their location.

    • API used for prospect creation: https://ozmap.stoplight.io/docs/ozmap/eeaee17d5416c-create-a-prospect

CRM

• Basic features

  • Technical Feasibility – Perform a query in OZmap by inputting the coordinates of a potential new client to receive a list of distribution boxes or buildings with available ports to serve the client at this location. To assess feasibility by searching for boxes and buildings, two requests are needed: Feasibility by radius (or pole) and Feasibility of buildings.

    • API used for feasibility by radius: https://ozmap.stoplight.io/docs/ozmap/8ffbbff600cd5-viabilidade-por-raio

    • API used for building feasibility: https://ozmap.stoplight.io/docs/ozmap/05378a036dcc2-viabilidade-de-condominios

    • API usage description in OZmap: Feasibility

  • Port Reservation – Create a property for a client not yet installed in OZmap, representing a client who has not been activated, reserving a port for future activation.

  • API used for client creation: https://ozmap.stoplight.io/docs/ozmap/180b1534fb63f-cria-um-imovel

  • API usage description in OZmap: Port reservation

  • Port Reservation Cancellation – Remove a client from OZmap's port reservation after the installation request is canceled.

    • API used for reservation cancellation: https://ozmap.stoplight.io/docs/ozmap/86688c5b178ac-exclui-um-cliente

    • API usage description in OZmap: Cancel a Client/Reservation

• Advanced Features

  • Client Implantation – Update the deployment status of a port reservation client to "Implanted," converting this port reservation into an activated client after installation is completed.

    • API used for client installation: https://ozmap.stoplight.io/docs/ozmap/934d26a9b4202-update-a-client

    • API usage description in OZmap: Implantation/Client activation

  • OZloc Module for Feasibility and Port Reservation – Use the OZloc module to perform feasibility checks and port reservations easily, either by coordinates or text address, considering all available network elements for client connection in OZmap. It supports different feasibility methods according to OZmap settings, without needing API requests. It can be initiated by passing client data via URL parameters or using an iframe to receive the created reservation data from OZmap as a return.

    • OZloc usage description: OZloc - English ver.

  • Prospect Creation – Create a prospect in OZmap to record clients who requested internet service but currently lack technical feasibility at their location.

    • API used for prospect creation: https://ozmap.stoplight.io/docs/ozmap/eeaee17d5416c-cria-um-prospect

Field Service

• Element Synchronization – Periodically fetch elements from OZmap for creation, editing, or deletion in the integrator system. This fetch can consider creation dates, last update, or deletion dates for each action. The purpose is to maintain a replica of OZmap network elements in the integrator's database. Examples of elements for synchronization include distribution boxes, splitters, and others.

  • API used for box retrieval: https://ozmap.stoplight.io/docs/ozmap/c7742f0fb1e29-lista-as-caixas

  • API used for splitter retrieval: https://ozmap.stoplight.io/docs/ozmap/8337d3f9dc1c6-lista-os-splitters

4o

FAQ