Welcome, Integrator! This documentation is a guide designed to facilitate the integration process with OZmap from the beginning. Here, you will find detailed instructions on how to contact the OZmap integration team, request access to the OZmap Sandbox for testing, and a list of recommended features for each type of integrating software, including usage tutorials.
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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 integrations@ozmapintegracoes@ozmap.com.netbr. 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 (NOT TRANSLATED YET): https://ozmap.atlassian.net/l/cp/PD97zCxG 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 (NOT TRANSLATED YET): https://ozmap.atlassian.net/l/cp/g3kyTUbL 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 (NOT TRANSLATED YET): https://ozmap.atlassian.net/l/cp/rZK5r6FF 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 (NOT TRANSLATED YET): https://ozmap.atlassian.net/l/cp/377jZeur 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 (NOT TRANSLATED YET): OZloc; 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 (NOT TRANSLATED YET): https://ozmap.atlassian.net/l/cp/5uWdHXaP 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: https://ozmap.atlassian.net/l/cp/808wyvKC 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
Customer 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 with customers in OZmap.
API for updating customer status: https://ozmap.stoplight.io/docs/ozmap/934d26a9b4202-atualiza-um-cliente;
API usage description (NOT TRANSLATED YET): https://ozmap.atlassian.net/l/cp/5uWdHXaP: Reading and updating a client status;
Update Customer Optical Power - Update the customers' 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: https://ozmap.atlassian.net/l/cp/808wyvKC 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 (NOT TRANSLATED YET): https://ozmap.atlassian.net/l/cp/MU231YLe: 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 (NOT TRANSLATED YET): https://ozmap.atlassian.net/l/cp/rZK5r6FF: 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 (NOT TRANSLATED YET)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.
atlassiannetlcp/377jZeur;
FAQ
Question | Answer |
|---|---|
Are all the features of the OZmap API available in the documentation? | No, this documentation is a work in progress. If you have any needs not covered in this document or at OZmap API documentation, please contact our integrations team to assist with your request. |
...