When you integrate PortaBilling with complex external systems, this may imply the provisioning of several of their subsystems (e.g., to provision the mobile core, you must provision data to the HSS and the PCRF). This can take time, as such systems have to wait for responses from their subsystems. Therefore, they provision the data asynchronously: a system accepts the request and sends notifications with the provisioning status (e.g., an hour later).
With the ESPF API interface, you can process these notifications and store the provisioning status for an account in PortaBilling. Consequently, you can verify your customer’s service activation and it also simplifies the provisioning of asynchronous systems.
You build the external application to provision subscriber data from PortaBilling and process notifications from your external system. Thus, the application must:
-
Receive provisioning events from the ESPF;
-
Query the obligatory subscriber data via the PortaBilling API;
-
Send the subscriber data to the external system using that system’s API;
-
Receive and process notifications from the external system;
-
Update the provisioning status for the account via the ESPF API.
The ESPF API is available under this URL:
https://<portabilling-web.yourdomain.com>/espf/v1/account/i/<i_account>/status
where:
- portabilling-web.yourdomain.com is the hostname of your PortaBilling web server;
- v1 is the provisioning event version;
- i_account is the unique ID of the PortaBilling account; and
- status is the account’s provisioning status.
You can also update the account’s provisioning status by using the account ID. Then the URL to send requests to changes to:
https://<portabilling-web.yourdomain.com>/espf/v1/account/ <account_ID>/status
The authorization is done using the PortaBilling administrative user’s API credentials.
The API request must include these parameters in JSON format:
|
Parameter |
Description |
|---|---|
|
status |
The account’s provisioning status. Possible values:
|
|
group |
A group organizes the provisioning requests per the external system (e.g., the IPTV group is used to identify provisioning requests to an IPTV platform). When the external system sends notifications, a group servers to distinguish them and store the account’s provisioning status. You can use any group name to store the account’s provisioning status. First, register this group in PortaSwitch and then pass its name to the ESPF in the API request. These groups are already registered in PortaSwitch:
|
This example illustrates how it works: Let’s say you integrate PortaBilling with the Order Management System (OMS) to provision the mobile core. The OMS is asynchronous and sends notifications about the provisioning status.
A new account with i_account=189 is created in PortaBilling and the ESPF sends the Account/New event to the external application.
The external application queries the SIM card details from PortaBilling via the API and provisions this data to the OMS. The OMS accepts the event and replies with 200OK to the external application. In 10 minutes, the OMS platform processes the event and sends the HTTP notification with the provisioning status to the external application. The external application sends the API request to the ESPF to update the account provisioning status:
POST
Request URL: https://mybilling.com/espf/v1/account/i/189/status HTTP/1.1
Host: https://mybilling.com
Content-Length: 19
Content-Type: application/x-www-form-urlencoded
{
"status": "OK ",
"group" : "HSS"
}
