ISP Flow
This document outlines the workflow and endpoints required for managing Internet Service Provider (ISP) operations. Below are the steps involved, along with descriptions of each endpoint, parameters, and example responses.
Overview
The ISP Flow is a process that enables the creation of services and customers within the AEx system. This includes several key steps such as:
- Customer Creation: Registering new customers in AEx.
- Check Customer: Verifying if a customer already exists in AEx.
- Predefine-Premise Lookup: Looking up predefined premises linked to a customer's address.
- Product Availability: Checking if the desired products or services are available at the customer's location.
- Service Creation: Activating a service for a customer after verification.
- Retrieve Premise Details: Check premise details.
- Retrieve Service Details: check service details.
This flow includes processes such as creating accounts, Creating services, looking up premise.
NOTE: please contact your SDM for a TOKEN to be used for the below endpoints.
- Additional Endpoints:
- Customer Service: Returns the current service for a customer.
- Customer Service Workorder: Check the current workorder for a given service.
Step 1: Customer Sign-up
Endpoint: POST /customers
-
Description: This endpoint is used to register a new customer as an ISP.
This includes collecting necessary customer details for account creation. -
Request Parameters:
first_name
(string, required): The customer's first name.last_name
(string, required): The customer's last name.email
(string, required): The customer's email address.password
(string, required): The customer's password.mobile_number
(string, required): The customer's mobile phone number.home_number
(string, optional): The customer's home phone number.
Example cURL Request:
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Example Request:
Example Responses:
-
201 Created: No response body.
-
400 Bad Request: If a customer already exists within AEx, the below error will occur.
Continue to - Check Customer to return the correct customer Guid. -
401 Unauthorized: You do not have access; please contact your SDM for a Token.
Step 2: Check Customer
Endpoint: GET /customers
-
Description: This endpoint checks if a customer exists in the ISP system by using either their ID or email address. It retrieves the necessary customer details based on the provided identifier.
-
Request Parameters:
q
(string, required): The customer's email used for querying.count
(integer, optional): The number of results to return (default is 10).page
(integer, optional): The page number of results to return (default is 1).
-
Example cURL Request 1: Based on email
-
Example cURL Request 2: Based on customer GUID
Example Responses:
-
200 OK: Returns customer details.
-
401 Unauthorized: You do not have access; please contact your SDM for a Token.
Step 3: Predefine Premise Lookup
Endpoint: GET /predefined-premises
-
Description: This endpoint retrieves a list of predefined premises based on a search query. It allows filtering by name and location and supports pagination.
-
Request Parameters:
q
(string, required): The search query string for the premises (e.g., address).count
(integer, optional): The number of results to return per page (default is 10, maximum is 100).page
(integer, optional): The page number of results to return (default is 1).
Example cURL Request:
Example Responses:
-
200 OK: Returns Predefine premise details.
-
401 Unauthorized: You do not have access; please contact your SDM for a Token.
Step 4: Product availability
Endpoint: GET /products/availability/{latitude}/{longitude}
-
Description: This endpoint retrieves a list of available products based on the specified latitude and longitude. It provides information about the products offered in that geographic area.
-
Request Parameters:
latitude
(float, required): The latitude of the location to lookup products (e.g.,-29.7872215658
).longitude
(float, required): The longitude of the location to lookup products (e.g.,30.9834343322
).
Example cURL Request:
Example Responses:
-
200 OK: Returns product details.
-
401 Unauthorized: You do not have access; please contact your SDM for a Token.
Step 5: Service Creation
Endpoint: POST /services/full
-
Description: This endpoint creates a new service by providing customer details, premise information, and service product details.
-
Request Body:
- customer: Object containing customer details.
id
(string, required): Unique identifier for the customer (e.g.,"4348AEF7-AD89-4309-AC29-DCB621C308CF"
).first_name
(string, required): Customer's first name (e.g.,"Customer20241008"
).last_name
(string, required): Customer's last name (e.g.,"Customer20241008"
).email
(string, required): Customer's email address (e.g.,"Customer20241008@postmantest.co.za"
).username
(string, required): Customer's username (e.g.,"Customer20241008@postmantest.co.za"
).mobile_number
(string, required): Customer's mobile number (e.g.,"1234567895"
).
- premise: Object containing premise details.
external_reference
(string, required): Unique reference for the premise (e.g.,"287C94C4-0196-4999-9348-15ACC0EE7A0A"
).
- service: Object containing service product details.
product_id
(string, required): Unique identifier for the service product (e.g.,"50726131-B525-4732-A2D5-0B3736CDFB69"
).
- customer: Object containing customer details.
Example cURL Request:
Example Request:
-
201 Created: Returns the details of the created service.
-
401 Unauthorized: You do not have access; please contact your SDM for a Token.
2. 400 Bad Request: Invalid request data; currently only returns Unauthorized on failure.
Step 6: Retrieve Premise Details
Endpoint: GET /premises/{premiseId}
-
Description: This endpoint retrieves the details of a specific premise using its unique premise ID.
-
Request Parameters:
premiseId
(string, required): The unique ID of the premise to retrieve (e.g.,4BF2A897-A38C-4D24-82C6-F2184C8832E4
).
-
Example cURL Request:
Example Responses:
-
200 OK: Returns product details.
-
401 Unauthorized: You do not have access; please contact your SDM for a Token.
-
404 Not Found: The specified premise ID does not exist.
Step 7: Retrieve Service Details
Endpoint: GET /services/{serviceId}
-
Description: This endpoint retrieves the details of a specific service using its unique service ID.
-
Request Parameters:
serviceId
(string, required): The unique ID of the service to retrieve (e.g.,34A39B28-8547-4853-9CAC-56F168EDE9D2
).
-
Example cURL Request:
Example Responses:
-
200 OK: Returns product details.
-
401 Unauthorized: You do not have access; please contact your SDM for a Token.
-
404 Not Found: The specified premise ID does not exist.
Check customer service
Endpoint: GET /customers/{customerId}/services
-
Description: This endpoint retrieves current service(s) that is linked to a customer.
-
Request Parameters:
customerId
(string, required): The unique ID of the customerId to retrieve (e.g.,34A39B28-8547-4853-9CAC-56F168EDE9D2
).
-
Example cURL Request:
Example Responses:
-
200 OK: Returns service details.
-
401 Unauthorized: You do not have access; please contact your SDM for a Token.
-
404 Not Found: The specified premise ID does not exist.
Check customer service work order
Endpoint: GET /work-orders?service={serviceId}
-
Description: This endpoint retrieves current work-order(s) for the given service.
-
Request Parameters:
serviceId
(string, required): The unique ID of the serviceId to retrieve (e.g.,34A39B28-8547-4853-9CAC-56F168EDE9D2
).
-
Example cURL Request:
Example Responses:
-
200 OK: Returns work-order details.
-
401 Unauthorized: You do not have access; please contact your SDM for a Token.
-
404 Not Found: The specified premise ID does not exist.