This document provides information for developers who want to interface their applications with PortaBilling via XML and JSON API. The PortaSIP Media Applications XML and JSON API is described in the PortaSIP Media Applications XML/JSON API Reference Guide.

Performing operations via the API has several advantages:

• It is based on either XML/SOAP (Simple Object Access Protocol) or JSON (JavaScript Object Notation) Web Application Services and HTTPS transport, so is accessible from any platform or operating system, and all server and client communications are secure.
• The business logic embedded in the API provides integrity checks for all data modifications, and can also compile records from several database tables to create a single customer information retrieval structure.
• The PortaBilling® API is accessible to every owner of a virtual environment or to every reseller. Each user's access is automatically limited to his "visible" portion of the available data, e.g. a reseller can only retrieve information about his own sub-customers or their accounts.

By default, all API requests that contain attributes with the date and time must be sent within the UTC timezone. The date and time attributes must be in the following format:

date: 'YYYY-MM-DD' time: 'HH24:MM:SS' datetime: 'YYYY-MM-DD HH24:MM:SS'

The API returns date and time information in the UTC timezone, respectively. Please note that some methods can receive and return date and time information in timezones different from the UTC (e.g. UTC+08). In these cases, the attributes of such methods contain the appropriate descriptions.

Connection to the XML/JSON API is provided via HTTPS. Authentication is done using a pair: a user login and either the API access token or the user password for the admin web interface. Each request to the API should contain the AuthInfoStructure structure as the header attribute.

Note that we strongly recommend using the session_id property (which must be received during the authorization via the login request) in the AuthInfoStructure structure for all session requests. Otherwise, if you use the login-password or the API access token authentication pairs for every request, new sessions will be created and cause additional load to the database.

The example below illustrates the login request in JSON format using the cURL command line tool:

curl https://demo.portaone.com:443/rest/Session/login -d params='{"login":"demo","password":"pAssw0rd"}'

The response returns the session ID value:

{"session_id":"527865ee75368ff2d2c4f4881cd2758a"}

• There is a wide range of reusable software available to programmers to handle XML so they do not have to re-invent code.
• XML (SOAP) is more verbose compared with JSON, but because of this, the data encoding result is typically larger than the equivalent encoding in JSON API.

Access to XML API

All SOAP requests to PortaBilling API must be sent to the following URL:
https://portabilling-web.yourdomain.com:port/soap/

Please replace the portabilling-web.yourdomain.com with the actual hostname of your PortaBilling web server.

Replace 'port' with the required port. The SOAP interface is available for administrators on port 443, the interface for customers is available on port 8444, the interface for resellers is available on port 8442 and the interface for accounts is available on port 8445.

Error Handling

SOAP faults are used to carry error information within a SOAP message. If the actual response has a SOAP fault element as the body entry, then an error has occurred. In this case, any other fields in the response cannot be guaranteed as accurate; only the fault sub-elements should be used to identify an error. Currently, these sub-elements are:

• faultcode is intended for use by the client software and provides an algorithmic mechanism for identifying the fault;
• faultstring provides a human readable explanation of the fault, and is not intended for algorithmic processing.

As an alternative to XML API, PortaBillling supports JSON API, thus providing your development department with a choice of Web Application Services that can be used. Among the advantages of JSON API are the following:

• Simple data structures that can be easily read and written.
• JSON format is faster in parsing and generating data due to simple syntax, thus there is little influence on web server performance.
• Supports the same methods as those in the SOAP.
• Simplifies the creation of front-end web sites that receive and modify data in PortaBilling with minimum impact on performance.

Access to JSON API

All JSON requests to PortaBilling® API must be sent to the following URL:
https://portabilling-web.yourdomain.com:port/rest/service/method/

Please replace the portabilling-web.yourdomain.com with the actual hostname of your PortaBilling web server.

Replace 'port' with the required port. The JSON interface is available for administrators on port 443, the interface for customers is available on port 8444, the interface for resellers is available on port 8442 and the interface for accounts is available on port 8445.

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 get_account_info method in order to get an account record from the database.)


Here is an example of the URL to send a POST request to:
https://demo.portaone.com:443/rest/Account/get_account_list/

Sending an HTTP request

For HTTP requests you must include the following parameters (in JSON format) in the POST request body:

• auth_info - The mandatory authentication information (see the Security section).
• 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.

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

You can run JSON requests in the asynchronous mode so that they are executed in the background. For this, add the aux_info structure as the additional argument into the request. The structure has the following fields:

• async - indicates that the method must be run in the asynchronous mode.
• bg_request_id – the ID of the background task started.
• dry_run – indicates that the method must be run in the dry run mode (possible values: all, simple).

NOTE: The asynchronous API requests are not processed during the software upgrade.

Examples

The examples below illustrate sending API requests using the cURL command line tool.

1. Receive the information about a subscriber:
   
   curl https://demo.portaone.com:443/rest/Account/get_account_info -d auth_info='{"session_id":"527865ee75368ff2d2c4f4881cd2758a"}' -d params='{"i_account":"2194329"}'
   
2. Run an API request in the asynchronous mode:
   
   curl https://demo.portaone.com:443/rest/Account/get_account_info -d auth_info='{"session_id":"527865ee75368ff2d2c4f4881cd2758a"}' -d params='{"i_account":"2194329"}' –d aux_info='{"async":"1"}'
   
3. Perform advanced customer data search:
   You can perform an advanced customer/account data search by using the get_extended_data_list API method. To make this happen, create a custom JSON request where you specify an object (e.g. Customers or Accounts) and the filters to be used for data search. A filter can be a property of a different object (e.g. Invoice.invoice_total); several filters can be linked with each other.
   The example below illustrates how to filter customers by country and invoice amount:
   
   https://demo.portaone.com:443/rest/Generic/get_extended_data_list/ -d auth_info='{"session_id":"527865ee75368ff2d2c4f4881cd2758a"}' -d params='{"data":[{"object":"Customers","fields":["*"]}],"filters":[{"entries":[{"object":"Customers","field":"country","values":["US"]},{"object":"Invoices","field":"amount_paid","values":[50]}]}],"get_total":1,"offset":0,"limit":50}'
   

Error Handling
If the server returns the '500 Internal Server Error' status code in the HTTP response, then the response body contains a JSON object which includes two elements (keys) that carry error information:

• faultcode, that is intended for use by the client software and provides an algorithmic mechanism for identifying the fault.
• faultstring, that provides a human readable explanation of the fault, and is not intended for algorithmic processing.

The PortaBilling® XML/JSON API is backward compatible. This allows your applications to communicate with new versions of PortaBilling® with very little reconfiguration.
Some API methods can become obsolete. They are kept for a few MRs and can be deleted once the first LTS release after the one where the method became obsolete is crossed. For instance, if an API method is found to no longer be useful in MR67, it can be deleted in MR71 onwards.

You can still enable obsolete API methods by adding the [API]AllowObsoleteMethods=1 option for the WebCustom group on the Configuration server. However, we don’t recommend it since using them alongside the new API logic may result in the incorrect operations of your applications. Instead, we recommend that you keep your API applications up to date.