Order Placement

The API enables new order placement by providing endpoints to allow coverage & premise availability checks based on a physical address. Once it has been determined that an order may be placed at the given address, endpoints are available for the account creation process.

Note: The capture of payment details is provided by a separate API, defined in the Payment Management section.

The outcome of a successful order placement is a Service, defined by the 3 Ps - a Person with a Premise and a Product (or Package).

Premises Availability Check

Before an order can be placed, the availability of the location has to be determined. A given address is available to accept new orders if the area has connectivity and does not have a currently active service.

To determine the availability of the location, its corresponding record must first be found in the system. The location search can be done in one of two ways: - Physical Address Search - Geographical Coordinates Search

Once an address or predefined premise ID have been found, a call can be made to the Location Details endpoint to get details including availability.

If the availability status in the response payload is true, then a new order may be placed at the address. However, if it is false then this means the location is not available and a new order may not be placed.

In some cases, the physical location where the order is being placed may not have an existing Premise record on the AEx system. In such a scenario, the premiseId in the response body for the details endpoint will have no value, and a new Premise record will have to be created by calling the endpoint described in the New Premise Creation section below.

Product Selection

Upon establishment of Premise availability, among the attributes that can be retrieved from the response body of the detail endpoint in the Premises Availability Check section is the areaId. This uniquely identifies a geographical area in the AEx Inc. internal systems, and it can be used to check which ISP Products are available in a specified area.

GET https://stage.provider-service.dev.aex.systems/products/:areaId

Get Available Products

[
  {
    "id": "a435d8a6-bc64-4420-a1f7-009f54ef0902",
    "provider_id": "e8da6ef7-a254-4004-a1df-4821a3dd25f4",
    "name": "PROMO 30/30 Mbps Uncapped Internet",
    "description": "Free Installation, Free Connection, Router & R50 Calltime...",
    "code": null,
    "speed_up": "30",
    "speed_down": "30",
    "effective_date": "2023-10-31T00:00:00",
    "status": "Active",
    "type": 3,
    "line_type": "broadband",
    "category": "Residential",
    "is_auto_recharge": false,
    "pricing": [
      {
        "id": "3354d932-6068-46a3-913e-257d48478639",
        "price_type_id": 2,
        "currency_code": "ZAR",
        "tax": 0,
        "code": null,
        "description": "Free Installation, Free Connection, Router & R50 Calltime...",
        "min_quantity": null,
        "value_excl_tax": 485,
        "value_incl_tax": 485
      }
    ]
  }
]

The response payload contains a list of all products that are Active and set to be available to ISP customers for signup.

Note: The Products that are returned in the response will only be for the ISP related to the token used in the Authorization header.

Customer Creation

For the final piece of the puzzle before being able to complete an order, we need the third P, customer details. The customer creation process is described here.

Service Creation

At this point, you should have the 3 Ps required to commence with service creation - the person ID, premise ID, and product ID. The process to get each of these is described in the preceding sections.

The endpoint for service creation is:

POST https://stage.provider-service.dev.aex.systems/services

Create Service

{
  "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "premise_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}