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.

View the list of API changes as a PDF document.

• It is based on either XML/SOAP (Simple Object Access Protocol) or JSON (JavaScript Object Notation) Web Application Services and HTTPS transport, so it is accessible from any platform or operating system, and all communication between the server and clients is secure.
• The business logic embedded into the API provides integrity checks for all data modifications, and can compile records from several database tables to create a single customer information retrieval structure.
• PortaBilling API is accessible to every owner of a virtual environment or 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.

• 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/auth_info/parameters/bg_info/

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.)

Replace 'auth_info' with your credentials to access the PortaBilling web server. See the AuthInfoStructure for details.

Please note that values that have int or float types (according to this guide), will be represented in the JSON responses by a string containing a number, like in the following example:

Here is an example of the URL to send a POST request to:
https://demo.portaone.com:443/rest/Account/get_account_info/{"login":"password"}/{"i_account": "123456"}/

You can run JSON requests in the asynchronous mode so that they are executed in the background. For this, add the aux_info structure 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).

Here is an example of the URL to run the API method in asynchronous mode:
https://demo.portaone.com:443/rest/Account/get_account_info/{"login":"password"}/{"i_account": "123456"}/{"async":"1"}

NOTE: The asyncronous API requests are not processed during the software updrade.

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 HTP POST request must have one of the following values:

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

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.