API Guide for Personal Cabinet

This document covers the control panels' APIs. You need to be logged in with the appropriate privileges to call a function. GET" and "POST" methods are supported.

Authentication methods

---

Session unique ID authentication

You can use this method when working with a control panel through your web browser.

Follow the link:

https://billing.sclad.us/billmgr?out=xml&func=auth&username=user_name&password=password

The control panel will return either an error message or the following XML document:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
<auth id="session id"/>
</doc>

You should specify this session id in the auth parameter to each call to a control panel. The session id is valid for one hour. If you do not send any requests to the control panel during that period, you will have to get authorized again.

https://billing.sclad.us/billmgr?auth=session_id&out=xml&func=function&parameter1=value&parameter2=value

authinfo authentication

This method can be used for remote function calls. To call a BILLmanager function, you need to add the authinfo parameter and specify a login and password of the user who will call that functions:

https://billing.sclad.us/billmgr?authinfo=admin1:mypasswd&out=xml&func=function&parameter1=value&parameter2=value

You must send the authinfo parameter with each call to the control panel. Authorization via "authinfo" can be restricted to the "white list" of IP addresses and/or networks. You can configure the "white list" through the "RestrictAuthinfoRange" and "Option RestrictAuthinfo" parameters of the configuration file or through the authorization settings.

Getting data from URL

---

To get the desired function and its parameter values, study the URL of the form in the billing platform.

For example, the URL for a specific payment. Go to Clients → Clients → select a client → click Payments → select a payment → click Edit. The URL of the payment modification form will look like this:

Payment URL

https://billing.sclad.us/billmgr#/?func=payment.edit&elid=1256&elname=pfx%2F1256&plid=334

• func=payment.edit — function for changing the object, viewing its parameters and creating a new object (payment)

• plid — client id

• elid — payment id

• elname — payment number (payment name)

To get the link in the interface, click the icon next to the title of the section you are in.

Calling function with the privileges of another user

---

To call an function with the privileges of another user, add su=user_name to the URL. A server administrator can call functions as any user; resellers can do so with the privileges of their user accounts. All other users cannot use this method.

Getting results in native languages

---

To get function results or error messages in your native language, add the lang=language to request (e.g. lang=en). If you specify a non-existent language, a default language will be used (normally, it is English, en)

Output of function results

---

Output can be generated in XML, JSON and text format. If you wish to receive output results in a specific format, specify the out=format_name parameter.

The out parameter can have one of the following values:

• xml — data structures in XML will be generated.

• devel — similar to XML, but the document will contain data describing the user's interface.

• text — data structures in the text format will be generated

• json — data structures in JSON will be generated. More information can be found here.
• JSONdata — similar to JSON. Only data are described

• print — html for printing. Can be used only for data lists

• xxxx — you can create a custom output format if needed

If the out parameter is missing, such data are considered to be used by the browser and are converted into HTML.

Operation confirmation

---

The "sok=ok" parameter in the request emulates clicking on the action confirmation button (Ok, Apply, Add to Cart, etc.) to submit various forms in the BILLmanager interface. For example, editing a tariff plan.

Sending a request without the "sok=ok" parameter is similar to opening a form. To apply the passed values, add the "sok=ok" parameter to the request.

Not all functions that change something are forms. In such functions, the "sok=ok" parameter may not be used.

In queries that aim to get current values, the "sok=ok" parameter is not used.

Local calls to control panel

---

For local calls to the control panel, you can use the internal utility mgrctl, which has a number of advantages

• calls are sent directly to the control panel (they do not depend on the web-server)

• there is no need to store a password, as authentication is always made with permissions of the user who run the script (if you need to perform operations as another user, use the su parameter described above).

• has built-in hints to all functions and their parameters relevant to your server

PHP enables to use URL like standard files. The DOM XML library is used to handle XML documents:

<?php
   $result = "";
   $fh = fopen( "http://billing.sclad.us/billmgr?out=xml&func=pricelist", "r" );
   while( $data = fread( $fh, 4096 ) ){
     $result .= $data;
   }
   fclose( $fh );
 
   // The $result variable contains either an XML document with tariffs,
   // or an error message
 
   if( $doc = domxml_open_mem( $result ) ){
      $root = $doc->document_element();
      for( $elem = $root->first_child(); $elem; $elem = $elem->next_sibling() ){
         for( $node = $elem->first_child(); $node; $node = $node->next_sibling() ){
            if( $node->node_name() == "name" ){
               echo $node->get_content();
               echo "\n";
            }
         }
      }
   }
?>

---

Requests are described as follows:

Function: a function name to be passed in the func parameter.

Parameters: a list of parameters and their brief description. If a function has no parameters, they are not specified. Parameters are passed in the format parameter=value.

Result: results may vary depending on the requested function:

List of elements (table)

The XML document will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elem>element parameters on the list</elem>
	<elem>element parameters on the list</elem>
	...
	<elem>element parameters on the list</elem>
</doc>

Result: only the element parameters are described. They are one or several XML-nodes containing all possible attributes and values. For example:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elem>
		<name>foo.org</name>
		<admin>foo_admin</admin>
		<php/>
		<ssi/>
		<user used="1" limit="10"/>
		<disk used="0" limit="10"/>
		<traf used="3542" limit="8192"/>
	</elem>
	<elem>
		<name>example.com</name>
		<admin>example</admin>
		<cgi/>
		<php/>
		<ssi/>
		<frp/>
		<user used="5" limit="50"/>
		<disk used="39" limit="50"/>
		<traf used="1084" limit="4096"/>
	</elem>
</doc>

List of object parameters (form)

The XML document will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <elid>unique object ID</elid>
    object parameters
</doc>

Result: the object parameters are only described. These are one or several XML nodes with all possible attributes and values that describe the properties of that object. For example:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elid>example.com</elid>
	<name>example.com</name>
	<gid>1001</gid>
	<alias>www.example.com test.example.com</alias>
	<cgi/>
	<phptype>phpcgi</phptype>
	<ssi/>
	<frp/>
	<sslport>443</sslport>
	<alluser>50</alluser>
	<shelluser>5</shelluser>
	<domain>1</domain>
	<base>3</base>
	<traf>4096</traf>
	<disklimit>50</disklimit>
</doc>

Successful operation (action)

When creating, changing, removing, enabling or disabling an object, the XML document will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<ok/>
</doc>

Delete requests return a response code of "200" even if no record is found. To verify that a record has been deleted, you can submit a request to edit the record. If the record is deleted, the request returns an error message.

Error message

If an error occurred while processing your request, the XML document will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<error>error message.</error>
</doc>