This documentation relates to an earlier version of JeraSoft VCS.
View User Guide 3.18 or visit our current documentation home page.
Skip to end of metadata
Go to start of metadata
On this page

The JeraSoft VCS API allows you to easily integrate 3rd party applications with JeraSoft's VCS platform or develop your own tools on top of it. You can use API to retrieve, add or modify data. Every object that you could use in the web interface can be accessed within API, be it client, rate or statistics report.

The JeraSoft VCS API may be accessed using either XML-RPC or JSON-RPC. Both are fairly standard protocols for remote procedure calls. Most programming languages have libraries to work with any of these protocols. The API uses the same logic as the web interface and works very similar, which makes its usage easier.

Access the API

To access XML-RPC interface use:

https://<your-system-IP>/xmlrpc/

To access JSON-RPC interface use:

https://<your-system-IP>/jsonrpc/

Before accessing the system make sure that your IP is allowed on the firewall. Also please make sure that rest of the world is blocked by firewall. You can get more details about it in the JeraSoft Billing First Steps.

Authentication

In order to make any request to the API you need to authenticate using login and password. We strongly recommend having separate API account for each application you make calls from. Besides this, we recommend having dedicated Role for API users, which allows only needed actions. Authentication is done by sending the following array along with other arguments:

{
   "auth": {
      "login": "admin",
      "password": "password"
   }
}

In order to increase performance you may not authenticate for each call but do it once and save Session ID given back to you in response. This Session ID may be sent in further requests instead of login and passwords to continue using same session without re-authentication. Session ID should be sent with other arguments in the following format:

{
   "SID": "1-dsglnqr4qnsdihr8djj6da7qr4"
}

It should be mentioned that authentication should be made within first call to the API.

API Request

Each request besides authentication information should include:

NameDescriptionExample
Method NameName of the module and action to call
clients.editForm
ArgumentsList of arguments for the method call
id_clients = 11
auth[login] = admin
auth[password] = password

API Response

Each response will include the following information:

NameDescriptionExample

code

Return code, usually true on success or false on failure
1

return

Array with data returned by method
[client] => Array
(
[id] => 11
[id_companies] => 3
[type] => 0
[name] => Customer A
[groups] => Customers
[c_dt] => 2013-03-30 16:26:15+03
[status] => active
[credit] => 100
...
)
session_idSession ID which may be used to speed up next calls
1-dsglnqr4qnsdihr8djj6da7qr4
messagesList of success / warning messages returned by message
array()
errorsList of abnormal errors if they fired during processing
array()

Work with files

There is a specific case when your request to billing should provide file response. Some examples of this would be an invoice file download, CDRs List download, etc. Using plain XML-RPC or JSON-RPC with base64 on top of it is not effective here as the file may contain hundreds of megabytes. This special case is handled with common HTTP Request to:

https://<your-system-IP>/admin/

The request may be either GET or POST and should include either Login and Password or Session ID. In response the server will send the file according to HTTP protocol.

Examples: Pure XML-RPC

XML-RPC Request
<?xml version="1.0" encoding="iso-8859-1"?>
<methodCall>
<methodName>clients.editForm</methodName>
<params>
 <param>
  <value>
   <struct>
    <member>
     <name>id_clients</name>
     <value>
      <int>11</int>
     </value>
    </member>
    <member>
     <name>auth</name>
     <value>
      <struct>
       <member>
        <name>login</name>
        <value>
         <string>admin</string>
        </value>
       </member>
       <member>
        <name>password</name>
        <value>
         <string>password</string>
        </value>
       </member>
      </struct>
     </value>
    </member>
   </struct>
  </value>
 </param>
</params>
</methodCall>
XML-RPC Response
<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>code</name>
            <value>
              <boolean>1</boolean>
            </value>
          </member>
          <member>
            <name>session_id</name>
            <value>
              <string>1-dsglnqr4qnsdihr8djj6da7qr4</string>
            </value>
          </member>
          <member>
            <name>messages</name>
            <value>
              <array>
                <data/>
              </array>
            </value>
          </member>
          <member>
            <name>return</name>
            <value>
              <struct>
                <member>
                  <name>client</name>
                  <value>
                    <struct>
                      <member>
                        <name>id</name>
                        <value>
                          <int>11</int>
                        </value>
                      </member>
                      <member>
                        <name>name</name>
                        <value>
                          <string>Customer A</string>
                        </value>
                      </member>
                      <member>
                        <name>groups</name>
                        <value>
                          <string>Customers</string>
                        </value>
                      </member>
                      <member>
                        <name>c_dt</name>
                        <value>
                          <string>2013-03-30 16:26:15+03</string>
                        </value>
                      </member>
                      <member>
                        <name>status</name>
                        <value>
                          <string>active</string>
                        </value>
                      </member>
                      <member>
                        <name>credit</name>
                        <value>
                          <double>100</double>
                        </value>
                      </member>
                    </struct>
                  </value>
                </member>
              </struct>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodResponse>

Examples: Pure JSON-RPC

JSON-RPC Request
{
  "method": "clients.editForm",
  "params": {
    "id_clients": 11,
    "SID": "1-bmdgeu6bn22jlmkuffg391t513"
  },
  "id": 1
}
JSON-RPC Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "code": true,
    "session_id": "1-bmdgeu6bn22jlmkuffg391t513",
    "messages": [],
    "return": {
      "client": {
        "id": 11,
        "name": "Customer A",
        "groups": "Customers",
        "c_dt": "2013-03-30 16:26:15+03",
        "status": "active",
        "credit": 100,
        "c_company": "Mancy",
        "c_address": null,
        "c_email": "admin@example.net",
        "c_email_tech": "admin@example.net",
        "c_email_billing": "admin@example.net",
        "c_email_rates": "admin@example.net",
        "id_currencies": 27
      },
    },
    "errors": []
  }
}

 

Examples: PHP Library

For you convenience it is always better to have higher level class on top of the simple RPC protocol. You can download example of such class for PHP. Below is example:

PHP Example
include 'class.VcsApi.php';
 
// create an API object
$api = new VcsApi('vcs.demo.jerasoft.net', 'demo', 'demo', 80);
 
// make a call to the API
$data = $api->clients->editForm(array('id_clients' => 8));
 
/*
VcsApiResponse Object
(
    [code] => 1
    [messages] => Array
        (
        )
    [data] => Array
        (
            [client] => Array
                (
                    [id] => 8
                    [id_companies] => 3
                    [type] => 0
                    [cc_serial] => 
                    [name] => Customer 01
                    [groups] => Vendors, IntraLATA-IntraState, IntraLATA-InterState, InterLATA-IntraState, InterLATA-InterState, Customers
                    [c_dt] => 2012-03-20 09:29:49+00
                    [status] => active
                    [credit] => 1000
                    ...
                )
        )
)
*/

 

Examples: Python Library

To download a sample library for Python please visit /usr/local/vcs/lib/pycore/tools/vcsapi.py. It will simplify work with  API. You can an example below:

Python Example
import vcsapi
 
# create an API object
api = vcsapi.Api('vcs-demo.jerasoft.net', 'demo', 'demo', 443)
 
# make a call to the API
response = api.clients.editForm({'id_clients': 8})

print response.code      # True
print response.messages  # [ ]
print response.data      # {'client': {'id': 8, 'type': 0, 'name': 'Customer 01', ...}}

 

Methods Reference

At the moment we are working hard to bring you full and detailed list of methods, arguments and expected output. However as API fully duplicates web methods, it is easy to find their names and arguments yourselves. Lets check a quick example, like creating a reseller. 

In the web interface the link to this action is "https://<your-billing-IP>/admin/companies/add", with "companies" being a module and "add" being a method. The resulting method to call via API is "companies.add"

In order to find out arguments for this method you may look for HTTP request in your browser (using FireBug in Firefox, Developer Tools in Chrome). Another way is to check for dump in /usr/local/vcs/var/log/runtime.log which looks like:

[20-Jan-2012 17:32:06+0200] [webAdmin/#260808] REQUEST: /companies/add
Array
(
    [type] => 10
    [name] => TESTCOMPANY
    [id_companies] => 
    [prepaid] => 1
    [credit] => 0.00
    ...
)

This log entry includes full list of the arguments used. However many of them are optional. Try calling method with the arguments you need - system will let you know if you are missing any of the arguments.

 

  • No labels