wiki:Administrators/Admin/API

API Guide

Introduction

Purpose of This Guide

External Application Integration Guide explains methods for external application to interact with Data Tech Labs Arrow Billing. It contains set of methods which allows to request particular data from system and in many cases insert and modify data in AB. This document is intended for system administrators and software developers only.

Principles

Request format

The request follows the standard HTTP protocol, just like what you do to browse the internet, additionally passes string containing request parameters and key used signature to verify validity of received request and authenticity of remote user. The query procedure is as follows:

  1. Open an socket connection to the AB host
  2. Send in the parameters in the format as stated further in this document
  3. Read the output from server and do whatever necessary parsing.
  4. Optionally wait for Billing System postback if you have requested it.

Request format is given below:

GET http://hostname/url?ver=<version>&format=<format>&request_type=<request_type>&username=<username>&<attr1>=<val1>&<attr2>=<val2>...&=&key=<signature> 

Explanations:

  • GET - http method
  • hostname - fully qualified hostname of Data tech Labs Arrow Billing
  • url - URL handling remote admin connection (fixed value: / billing/webscr.php)
  • version - protocol number specified by Data Tech Labs (fixed value = 2.0)
  • format - returned data format (1-txt, 2 - XML)
  • request_type - type of transaction, for example add New Account or Post Payment
  • username - User requesting data. It must exist in Arrow Billing and have appropriate privileges. You cannot use root account.
  • attr1...n - request specific attribute names
  • val1...n - request specific values
  • signature - security key, built in following way:
    1. Take all request string (as It will be sent to Arrow Billing), starting from "ver=" attribute and in EXACTLY same order as specified.
    2. Add following string at the end of it: "password=&" where - is accessing user's password as specified in Arrow Billing. Note trailing "&" at the end of the string
    3. Calculate MD5 hash of the resulting string and bring it to uppercase
    4. The resulting 32-character string will be "signature"
    5. Url-encodable values should be url-encoded AFTER hash calculation.

Response Format

currently only plain text mode will be supported. Returned values will pairs of attribute-value separated by '=' (equals) sign. Pairs will be separated by '|' (vertical bar or pipe) character. There will be ';' (semicolon) character after last value. The end of line will be designated by Newline character (\n). No data should follow after this character.

Error code return:

In case of error, system will return in following format:

##ErrorCode=XXXX

There are two types of error codes:

  1. Protocol Level Errors: they are common for any request type and are with value range within 100-999
  2. Request Specific Errors: they are specific to particular request and have value range 1000-1999

The list of Protocol-Specific Error Codes is provided below this Document. Request-specific error codes are explained along with each request definition.

List of Supported Request Types

Get Account Balance

request_type=get_balance
Availability

version 2.2.0 and higher

Changes

none

Description

Retrieves account balance and currency by Its Alias.

Attributes sent

account_alias - account Alias (username, phone number, PIN, H323ID or SIP username)

Values received:

  • BALANCE - account Balance
  • CURRENCY_ID - Account Currency ID
  • CURRENCY_NAME - Account Currency Name
  • CREDIT_LIMIT - Account Credit Limit
  • PREPAID - Is Account prepaid (1-YES, 0-NO)
  • STATUS_CODE - Status of account, one of following:
    • 00 - Account Enabled,
    • 01 - Account Disabled,
    • 02 - Account Pending Accept,
    • 03 - Account Expired
Request Error Codes
  • 1001 - account not found
  • 1002 - account is slave, data is not applicable

Get Rate

request_type=get_rate 
Availability

version 2.2.0 and higher

Changes

none

Description

Retrieves rate table detail information for account based on its Alias (username)

Attributes sent
  • account_alias - account Alias (username, phone number, PIN, H323ID or SIP username)
  • dest_number - destination number of call
  • access_dnis - DNIS of Access number which may be passed as optional attribute. If this attribute is passed, system will look up matches in DNIS Charge table and will add Rate per Minute and Rate per Call if match found
Values received
  • RATE_M - Rate per Minute
  • RATE_C - Rate Per Call
  • CURRENCY_ID - Rate Currency ID
  • CURRENCY_NAME - Rate Currency Name
  • INCREMENT - increment step, seconds
  • GRACE - grace time, seconds
  • MIN_FLEX - minute flexibility feature, number of seconds in minute
  • MIN_DUR - minimum call duration, seconds
  • DEST_NAME - description of destination, enclused in (" - double quotes)
  • ROUTING_GROUP - name of the Routing Group of this account in double quotes. NULL if no group is found.
Request Error Codes
  • 1001 - account not found
  • 1014 - destination number not received
  • 1015 - rate not found

Update Account

request_type=update_account 
Availability

version 2.2.0 and higher.

Description

Updates account with call information. It is equivalent to sending RADIUS Accounting message. Therefore it requires valid Data Source to be setup in AB.

Attributes sent
  • account_alias - account Alias (username, phone number, PIN, H323ID or SIP username)
  • dest_number - destination number of call
  • duration - duration of call in seconds (integer)
  • callid - unique call identified, aka H323conf ID (alphanumeric, max 32 characters). Calls with duplicate callIDs will be discarded.
  • calling_ip - calling party IP address
  • called_ip - called party IP address
  • nas_ip - Data Source (NAS) IP address
  • src_number - Calling Party Number
  • disc_cause - Q.931 disconnect cause, hex
  • access_dnis - DNIS of Access number which may be passed as optional attribute. If this attribute is passed, system will look up matches in DNIS Charge table and will add Rate per Minute and Rate per Call if match found
Values received
  • Returns message OK if successful or Error Code if failed
Request Error Codes
  • 1016 - could not find or no permission to execute
  • 1031 - other errors

Add New Account

request_type=add_account 
Availability

version 2.2.0 and higher

Description

Adds new account. This command mimics registration on the web

Attributes sent
  • email - email address
  • web_password - web access password
  • enable_weblogin - Set to "YES" to enable web login, Set to "NO" to disable the logging after account is created.
  • fname - first name
  • lname - last name
  • phone - phone number
  • product_id - product ID
  • iso_country - ISO country code (ISO-3166-2 two letter code)
  • web_profile_id - web profile ID (from which all other settings will be used)
  • ani - ANI for the account (optional). In case if this attribute is sent AND respective Webaccount Profile has Checkbox "Preferences: Allow Edit ANI Accounts" checked, the system will generate ANI account uder ANI tab. This behavior is similar to that which is when registering directly on selfregistration page.
Values received
  • ID=<ACCOUNT_ID>|USERNAME=<USERNAME>|PASSWORD=<PASSWORD>;
  • ACCOUNT_ID - new account ID (internal)
  • USERNAME - SIP username. For SIP account. The generation pattern isspecified by Webaccount Profile following fields: "Prefix Symbols in Account ID (starts with)", "Account ID Pattern Regex (leave blank for default)" and "Number of digits in Account ID (including prefix)"
  • PASSWORD - SIP password. randomly generated SIP account password of 8 symbols
Request Error Codes
  • 1002 - cannot insert account. Check if email already exists in the system.
  • 1003 - invalid alias format
  • 1004 - invalid status
  • 1005 - invalid auth type
  • 1006 - Product not found (check Webaccount profile)
  • 1007 - Currency not found (check Webaccount profile)
  • 1008 - Web profile ID not found
  • 1009 - Unable to insert username/password account
  • 1010 - Unable to insert ANI account. Check if ANI already exists in the system.

Recharge Account

request_type=recharge_account 
Availability

version 2.2.0 and higher

Description

Recharges account using Rechargeable PIN (Validation code)

Attributes sent
  • account_alias - account Alias (username, phone number or H323ID)
  • recharge_pin - digits of recharge PIN
Values received
  • AMOUNT - Amount which was credited to account
  • CURRENCY_ID - Recharged Currency ID
  • CURRENCY_ID - Recharged Currency ID
Request Error Codes
  • 1001 - account not found
  • 1016 - PIN is invalid
  • 1017 - PIN expired
  • 1018 - Agent balance insufficient
  • 1019 - other error, unspecified
  • 1020 - PIN is empty

Get List of Account Groups

request_type=list_groups
Availability

version 2.2.0 and higher

Description

Returns list of all account group names in a column. delimiter is newline ( \n ).

Attributes sent
  • no input attributes
Values received
  • List of all account group names in a column. delimiter is newline ( \n ).
Request Error Codes
  • None

Get List of Accounts In the Account Group

request_type=get_accounts_from_group
Availability

version 2.2.0 and higher.

Description

Returns list of all accounts and their passwords in the group. delimiter is newline ( \n ).

Attributes sent
  • group_name - name of the account group
Values received
  • List of all accounts and passwords. Fields delimited by pipe (|). Rows delimited by newline ( \n ).
Request Error Codes
  • 1021 - account group not found

Get Speed Dial Numbers

request_type=get_spdial
Availability

version 2.2.0 and higher

Description

Returns pipe delimited list of speed dial numbers with their associated shortnumbers for supplied account alias

Attributes sent
  • account_alias - account Alias (username, phone number or H323ID)
Values received
  • DIAL_X - Speed dial number for shortcode X. X values between 1 and 9. Value NULL returned if speeddial for given shortcode is not set.
Request Error Codes
  • 1001 - account not found

Set Speed Dial Number

request_type=set_spdial
Availability

version 2.2.0 and higher

Description

Sets speed dial number for this account

Attributes sent
  • account_alias - account Alias (username, phone number or H323ID)
  • spd_id - speedial shortcode, must be between 1 and 9
  • dest_number - destination number to store for this speeddial.
Values received
  • OK - on succesful function execution.
Request Error Codes
  • 1001 - account not found;
  • 1022 - spd_id attribute not found or invalid;
  • 1023 - dest_number attribute not found;
  • 1031 - other error,

Protocol and system level errors

  • 101 - INVALID USER
  • 102 - NO PERMISSION
  • 103 - DATABASE ERROR - Can not prepare
  • 104 - DATABASE ERROR - Can not open cursor
  • 105 - INTERNAL ERROR
  • 106 - NO RETURN
  • 107 - INFORMATION UNAVAILABLE
  • 108 - DATABASE ERROR - Can not connect to DB
  • 109 - INVALID KEY
  • 110 - MISSING ATTRIBUTE
  • 111 - INVALID REQUEST - request_type attribute not understood

Example

You would like to register new account via API. The incoming data is following:

  • Billing server url: http://192.168.0.1/billing/
  • API username: registrator
  • API password: secretpass
  • Alias - 7770777
  • password - 1234567
  • authtype - ANI or calling number
  • status - Enabled
  • product name - TestProduct
  • reseller ID - 0
  • Is master - No
  • Master ID - none
  • Balance - 4.99
  • Currency - USD
  • Creditlimit - 0.00

First, lets create list of attributes to be sent:

  • ver => 2.0
  • request_type => add_account
  • format => 1
  • username => registrator
  • alias => 7770777
  • passwd => 1234567
  • authtype => ANI
  • status => 1
  • productname => TestProduct
  • resellerid => 0
  • ismaster => NO
  • masterid => 0
  • balance => 4.99
  • currencyname => USD
  • creditlimit => 0.00

Let's construct string for checksum calculation:

ver=2.0&request_type=add_account&format=1&username=registrator&alias=7770777&passwd=1234567&authtype=ANI&status=1&productname=TestProduct&resellerid=0&ismaster=NO&masterid=0&balance=4.99&currencyname=USD&creditlimit=0.00

To calculate signature, we will add API password at the end of the string (note trailing &):

&password=secretpass&

String will look like:

ver=2.0&request_type=add_account&format=1&username=registrator&alias=7770777&passwd=1234567&authtype=ANI&status=1&productname=TestProduct&reseller
id=0&ismaster=NO&masterid=0&balance=4.99&currencyname=USD&creditlimit=0.00&password=secretpass&

Now lets get MD5 of the string and bring it uppercase:

5D5F722D93B39236787B2FC907805447

Remove password part from the end of the string and replace by key attribute-value pair:

ver=2.0&request_type=add_account&format=1&username=registrator&alias=7770777&passwd=1234567&authtype=ANI&status=1&productname=TestProduct&reseller
id=0&ismaster=NO&masterid=0&balance=4.99&currencyname=USD&creditlimit=0.00&key=5D5F722D93B39236787B2FC907805447

The string is ready for sending into Arrow Billing.

Last modified 3 years ago Last modified on Feb 11, 2015, 10:19:38 AM