Retrieving data from PortaBilling

When the Application receives a provisioning event, it connects to PortaBilling via the XML (SOAP) or JSON (REST) API to retrieve information about the modified entity.

Connection to the XML/JSON API is provided via HTTPS. To access the XML API, SOAP requests to PortaBilling API must be sent to the following URL:

https://[portabilling-web.yourdomain.com]:[port]/soap/[service]/[method]

To access the REST API, JSON requests to PortaBilling API must be sent to the following URL:

https://[portabilling-web.yourdomain.com]:[port]/rest/[service]/[method]

Replace [portabilling-web.yourdomain.com] with the actual hostname of the PortaBilling web server.

Replace [port] with the required port. The SOAP/JSON interface is available for administrators on port 443 by default.

Replace [service] with the API service that contains the required method (e.g., specify the Account service to manage account information.)

Replace [method] with the required API method (e.g., specify the get_account_info method to get the account information).

The Content-Type header field used with a HTTPS POST request must have one of the following values:

• application/x-www-form-urlencoded
• multipart/form-data
• application/json

The body of the POST request must contain the following parameters (in JSON format):

• auth_info – the mandatory authentication information such as login and password or login and API token (specified on the admin web interface). Upon successful authentication, an access token and session id are sent in the response body and included as response cookies. The following API requests can be made using the access token or session ID.
• params – a set of method parameters (in JSON format) that depend on a method structure. Note that method parameters and their structures are the same as those in the SOAP.

For connecting to the JSON API, use the session/login method. In response to the session/login method, the API user (an external application) receives the following fields: “access_token”, “expires_at”, “refresh_token”, and “session_id”.

Let’s see the details of these fields:

• access_token – can be used to call all the API methods regardless of whether they are related to PortaBilling, PortaSIP, or ESPF.

  To make authorized calls of other API methods, specify the access token in the “auth_info” parameter. Alternatively, the access token can be specified in the authorization header of the “Bearer” type (recommended).

  The access token contains info identifying the API user (e.g., i_user, i_env) that can be decoded (but not modified) and used in external applications. External applications can verify the access token even without access to the PortaBilling database by using the public key. This is useful, for example, when access to the database should be forbidden to third-party applications.

• expires_at – the date and time when the access token expires.
• refresh_token – used to update access tokens. When the access token lifetime (usually short) ends, an application can call the refresh_access_token method using the refresh token. Thus, the application can obtain a new access token to use for other API calls (and a new refresh token).

  You can implement a custom refresh flow for an external application using the get_access_token_lifetime method. For example, a new pair of tokens will be requested earlier than the access token expiration time – according to a custom timer. This ensures the application works without interruptions.

• session id – the unique ID of the newly opened authenticated session. It also can be used to call the other PortaBilling API methods but we recommend using an access token instead.

Note that for backward compatibility, the default lifetime of the access token is two days.

The session/login_to_realm method returns the same fields which are used similarly.

For more information, refer to the PortaBilling API reference (you can review methods and their parameters, request/response examples, and even call test requests).

To access the PortaBilling web server, the login request must contain a pair: a user login and either the API token or the user password for the admin web interface.

Here is an example of the POST request:

POST /rest/Session/login HTTP/1.1
Host: demo.portaone.com
Content-Type: application/json
{
"params": {
"login": "demo",
"password": "exAmple"
}
}

The response:

{
"session_id": "fb48b180539529497f3475c71e0bdc66",
"refresh_token": "836466a06bef49c38305afc14e13e487",
"expires_at": "2022-08-28 13:07:30",
"access_token": "eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2NjE2OTIwNTAsImlfdXNlciI6NDQwLCJpX2VudiI6NDEsImxvZ2luIjoiZGVtbyIsInNjb3BlcyI6ImVzcGYuYXBpOndyaXRlIGVzcGYuaGFuZGxlcnM6d3JpdGUiLCJpYXQiOjE2NjE1MTkyNTAsImp0aSI6ImZiNDhiMTgwNTM5NTI5NDk3ZjM0NzVjNzFlMGJkYzY2IiwicmVhbG0iOiJhZG1pbiIsImF1ZCI6WyJwb3J0YWJpbGxpbmctYXBpIiwicG9ydGFzaXAtYXBpIiwiZXNwZi1hcGkiXSwiaXNfc3VwZXJfdXNlciI6MH0.Qou3zbdFvF5bGup0tGrAvPAjoaeoeTMZQN3awMVOJAIKZGSLWL7kmhm3Xzjr05xZPQp3vrwtv4y4SygnXkzrcbYiIzzV-dcrANhRbOTnTPUMMU_t2rgNCG9Qo2eVzUv-4u_g1mVuBqx_8pIZs93g7C8-6O7XP_hg9Oo0BilB4W0jp0zjTxdp46sQ2aP2q7HZNLO6USL5vchxPGWPQp2VPL9cW4RRO71Ok2a4eGRir60ytvUz98fAlHtf-AUDFd3BkEltRN4BYyGGuWCeihengU0Z8DBucCmcQdAeUBbzo65D6V5ubSWOwUNvnjfHmmsqfS50G_7-GMKYaBqMfBRPmw"
}

Here is an example of following POST request (in JSON format):

POST /rest/Account/get_account_info HTTP/1.1
Host: demo.portaone.com
Content-Type: application/json
Authorization: Bearer 
eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2NjE2OTIwNTAsImlfdXNlciI6NDQwLCJpX2VudiI6NDEsImxvZ2luIjoiZGVtbyIsInNjb3BlcyI6ImVzcGYuYXBpOndyaXRlIGVzcGYuaGFuZGxlcnM6d3JpdGUiLCJpYXQiOjE2NjE1MTkyNTAsImp0aSI6ImZiNDhiMTgwNTM5NTI5NDk3ZjM0NzVjNzFlMGJkYzY2IiwicmVhbG0iOiJhZG1pbiIsImF1ZCI6WyJwb3J0YWJpbGxpbmctYXBpIiwicG9ydGFzaXAtYXBpIiwiZXNwZi1hcGkiXSwiaXNfc3VwZXJfdXNlciI6MH0.Qou3zbdFvF5bGup0tGrAvPAjoaeoeTMZQN3awMVOJAIKZGSLWL7kmhm3Xzjr05xZPQp3vrwtv4y4SygnXkzrcbYiIzzV-dcrANhRbOTnTPUMMU_t2rgNCG9Qo2eVzUv-4u_g1mVuBqx_8pIZs93g7C8-6O7XP_hg9Oo0BilB4W0jp0zjTxdp46sQ2aP2q7HZNLO6USL5vchxPGWPQp2VPL9cW4RRO71Ok2a4eGRir60ytvUz98fAlHtf-AUDFd3BkEltRN4BYyGGuWCeihengU0Z8DBucCmcQdAeUBbzo65D6V5ubSWOwUNvnjfHmmsqfS50G_7-GMKYaBqMfBRPmw
{
"params": {
"i_account":713,
"get_included_services":1,
}
}