OZmap x Alterpay Integration

The OZmap–Alterpay integration is passive, using API calls initiated by Alterpay to consume resources provided by OZmap. Unlike bidirectional integrations, Alterpay does not replace OZmap as the network documentation tool. OZmap remains the source of truth, maintaining the GIS design, poles, cables, boxes, splitters, and splice diagrams, while Alterpay only queries this information to support sales, pre-contract processes, provisioning, service monitoring, and service termination. 

The integration supports FTTH feasibility checks with port reservation, client/property deployment and updates, client and reservation cancellation, box, splitter, and port updates, as well as checking the OZmap integration link directly from the service details.


Alterpay → OZmap Integration

Almost all integration features are initiated by Alterpay and directed toward OZmap. The only exception is the integration link lookup, which retrieves data from OZmap to be displayed in Alterpay. 

Feasibility Check with Port Reservation in OZmap 

The feasibility check with port reservation consists of using the network documented in OZmap during sales, pre-contract, provisioning, or field operations in Alterpay to verify FTTH feasibility at a location and reserve a port for installation .

Coverage verification and the search for nearby boxes are not separate features — both are part of the same radius-based feasibility check. Alterpay queries OZmap using: 

  • Latitude;

  • Longitude;

  • Typical radius of 400 meters.


The process works as follows: 

  • The user enters or adjusts the installation point on the map in screens such as sales, pre-contract, provisioning, or field coverage;

  • Alterpay queries OZmap to check FTTH feasibility within the configured radius;

  • If there is availability, Alterpay displays the nearby OZmap boxes within the service radius, sorted by distance and showing the number of available ports;

  • The user can select a box and review the splitter port grid or, when enabled, Alterpay can automatically select the nearest box with at least one available port;

  • After selecting an available port, Alterpay can reserve the box port for the work order while the activation process moves forward.


The query can return three results: coverage available (viable FTTH resources exist within the radius), no coverage (no viable resources were found), or query error (the query failed, and the map keeps the last selected point for a new attempt).

If there are no boxes within the search radius, Alterpay indicates that no boxes are available. However, the sales process can continue without a selected box, and the link can be completed later from the service.


Port Statuses During Selection 


Only available ports can be selected for new activations: 

  • Available — port available for a new assignment; can be selected.

  • Occupied in OZmap — port is already shown as occupied in the documented network; cannot be selected.

  • Reserved by another work order — another Alterpay work order already has a reservation for this port; cannot be selected.

  • Blocked — port is unavailable for the sales process; cannot be selected.


Client/Property Deployment and Updates in OZmap

Client/property deployment and updates consist of creating or updating, from Alterpay, the operational record associated with the FTTH service in OZmap during provisioning or activation.

  • During provisioning or activation, Alterpay uses the box and port selected previously or allows this selection to be completed during the operational workflow.

  • Alterpay creates or updates the property in OZmap associated with the FTTH service.

  • Operational service metadata is synchronized, such as name, tags, deployment status, notes, and FTTH client.

  • If the provisioning is saved as a draft, the box, port, and property metadata remain preserved for later completion. 

This functionality maintains the link between Alterpay’s operational process and the client/property documentation in OZmap, without changing OZmap’s responsibility for network documentation.


Client and Reservation Cancellation in OZmap 

Client and reservation cancellation consists of releasing the client or property associated with the service when a service is terminated or canceled in Alterpay.

  • The user accesses the service details in Alterpay.

  • In the OZmap tab, they select the "Remove from OZmap" option.

  • Alterpay requests the release of the corresponding client or property in OZmap.

Unlike automatic deletion, disabling the map gateway in Alterpay does not remove existing properties from OZmap — the release must be explicitly performed through the service workflow when applicable.


OZmap Client Box, Splitter, and Port Updates 

The update of the client's box, splitter, and/or port in OZmap consists of changing, from Alterpay, the service's operational link information whenever it is necessary to adjust the box or port used by the client. 

This functionality can be used both in provisioning workflows and from the service details, maintaining the relationship between the Alterpay service and the structure documented in OZmap. When changing the box or port, Alterpay must respect the availability statuses returned by the integration, allowing selection only of ports with the Available status.

OZmap Link Lookup in the Service (OZmap → Alterpay)

The link lookup allows users to view, in Alterpay, the relationship data between the client’s service and OZmap. Under Clients → Service → OZmap, the following information can be viewed:

  • Integration status;

  • Deployment status;

  • Box and port;

  • FTTH client;

  • Property data;

In the same tab, it is also possible to edit information related to OZmap or release the client's relationship with the integration.


Where the Integration Is Used in Alterpay 


  • Sales — Commercial → Sales → Create → Map. Allows users to check FTTH feasibility, view nearby boxes within the service radius, select a box and port, and review reservation statuses. 

  • Pre-contract — Leads → Pre-contract → Location on the map. Allows users to set the installation point, edit latitude and longitude, check OZmap boxes within 400 meters, and view available, reserved, or occupied ports. If the Maps module is disabled, the OZmap Box card simply does not appear, and the rest of the pre-contract workflow continues to work normally. 

  • Provisioning — Operations → Provision. Allows users to select a box and port, maintain a port reservation on the box, and record the property metadata (name, tags, notes, deployment status). Provisioning can be saved as a draft at any stage, preserving this data for later completion. 

  • Service Details — Clients → Service → OZmap. Displays the integration status, deployment status, box and port, FTTH client, and property data, and also allows users to edit this information or release the client/property.

  • Field Applications — Sales representatives and installers use the same OZmap integration available in the Alterpay dashboard, maintaining a single source of truth for coverage, box selection, and port status analysis (Sales → Coverage and Pre-contract; Installers → Coverage). 



Integration Configuration 


The integration is configured in Alterpay under Configuration → Maps:

  • OZmap Integration Active — enables or pauses the use of OZmap as the company's Maps Gateway; it must be active to check feasibility, boxes, and ports.

  • OZmap API Key — authentication key for the OZmap tenant used by Alterpay; required and stored encrypted.

  • OZmap Subdomain — subdomain of the ISP's OZmap instance; required to validate the connection.

  • Feasibility Radius — radius used to check feasibility and nearby boxes, typically 400 meters.

To configure the integration, the user must go to Configuration → Maps, locate the OZmap Integration, enable the Active switch, open Settings (or Configure API / Keys), enter the OZmap API Key and subdomain, and click Validate and Save. During validation, Alterpay tests the connection by attempting to list the OZmap projects.

The integration can have the following statuses: 

  • Pending — the integration has not yet been validated; feasibility and resource queries may not be available.

  • READY / Ready — the credentials have been successfully validated; the integration is ready to query feasibility, boxes, ports, and synchronize operational data.

  • Other gateway statuses — indicate a specific connection issue or condition. The configuration, credentials, or connectivity should be reviewed.

If the integration is disabled, coverage screens may be hidden or indicate that the supported capacity is unavailable, and it will not be possible to query boxes or ports. However, other Alterpay features, such as billing, the portal, and tickets, continue to work normally. 


Required Data 

From the Alterpay side: 

  • Maps Module Enabled — the company must have the Maps module available to use OZmap as its gateway.

  • Configuration Permission — the user must have permission to configure integrations in Alterpay (administrator or authorized operator).

From the OZmap side: 

  • API Key — authentication key for the OZmap user/tenant used by Alterpay to send API requests.

  • Subdomain — subdomain of the ISP's OZmap instance (e.g., client.ozmap.com.br).

  • Active OZmap Account — the tenant must be operational and have projects available for validation.

Alterpay's documentation does not specify a dedicated IP allowlisting policy for this integration. If the client's environment uses network restrictions, it is recommended to check directly with the teams responsible for Alterpay and OZmap whether any additional allowlisting is required for inbound or outbound traffic. 


Common Issues

The integration does not appear

  • Check whether the user has configuration permissions.

  • Check whether the company has the Maps module enabled.

  • Check whether the OZmap integration is registered as the Maps Gateway.

Feasibility is not available

  • Check whether the Active switch is enabled.

  • Check whether the API Key is valid.

  • Check whether the subdomain is correct.

  • Check whether the integration status is READY / Ready.

The OZmap Box card does not appear

  • Maps is disabled.

  • The credentials have not been validated.

  • The company does not have feasibility checking enabled.

No nearby boxes are available

  • The search uses a radius of 400 meters. If there are no boxes within this radius, the workflow can continue without a box, and the link can be completed later from the service.

  • Recommendation: an installation should not be promised without confirming actual operational feasibility, even if the commercial workflow can continue without a box assigned.

The feasibility check fails

  • Use the "Try Again" option — the map keeps the last selected point.

  • If the issue persists, review the OZmap status, API Key, subdomain, connectivity, and integration status in Alterpay.