Remote API Guide

Table of Contents

Introduction

Purpose of This Guide

External Application Integration Guide explains methods for external application to interact with Arrow Telecom's 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.

Show Top

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=\
&format=&request_type=&username=&\
=&...&=&\
require_postback=YES|NO&postback_url=&key=
note that backslash (\) symbol designates continuosness of string and should not be included in request string.

Explanations:
  • GET - http method
  • hostname - fully qualified hostname of Arrow Telecom's  Arrow Billing
  • url - URL handling remote admin connection (fixed value: / billing/webscr.php)
  • protocol_version_number - 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.
  • require_postback - if set to YES, Arrow Billing will post back result to URL specified in postback_url attribute. If set to NO, postback will not be called.
  • postback_url - URL which will be called when Billing system completes request. Value must be url-encoded. "require_postback" attribute must be set to YES.
  • attr - request specific attribute name
  • value - request specific value
  • 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.
Respond Format:

currently only plain text mode will be supported. Returned values will pairs of attributevalue separated by '=' (equals) sign. Pairs wil 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. Requestspecific error codes are explained along with each request definition.

Show Top

List of Supported Request Types

Get Account Balance

request_type=get_balance
Availability: version 1.2.9 and higher, 1.3.0 and higher

Description:

Retrieves account balance and currency by Its Alias.

Attributes sent:

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

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 1.2.9 and higher, 1.3.0 and higher. Return attributes DEST_NAME and MIN_DUR available as of version 1.4.2

Description:

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

Attributes sent:
  • account_alias - account Alias (username, phone number or H323ID)
  • dest_number - destination number of call
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)
Request Error Codes:
  • 1001 - account not found
  • 1014 - destination number not received
  • 1015 - rate not found

Update Account

request_type=update_account
Availability: version 1.2.9 and higher, 1.3.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 or H323ID)
  • 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
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 1.2.9 and higher, 1.3.0 and higher

Description:

Adds new account.

Attributes sent:
  • account_alias - account Alias (username, phone number or H323ID)
  • passwd - account password
  • authtype - authentication type (USER - username, IPADDR - IP address, ANI - calling number)
  • status - Account status (1-Enabled, 0-disabled).
  • one of following:
    • rateid - Rate Table ID
    • ratename - Rate Table Name
  • one of following:
    • resellerid - Reseller ID ( 0 if no Reseller)
    • resellername - Reseller Name (empty string if no Reseller)
  • ismaster - Determines if this account is Master (1- Yes, 0- No)
  • one of following (if ismaster is 0):
    • masterid - Master Account ID (0 - if none)
    • masteralias - Master Account Alias (empty string if No Master)
  • one of following:
    • companyid - Company ID of account (0 - if none)
    • companyname - Company Name of account (empty string if No Account)
  • balance - Account Balance (attribute does not exist for slave accounts)
  • one of following:
    • currencyid - Account Currency ID (attribute does not exist for slave accounts)
    • currencyname - Account Currency Name (attribute does not exist for slave accounts)
  • creditlimit - Account Credit Limit (attribute does not exist for slave accounts)
Values received:
  • ACCOUNT_ID - new account ID
Request Error Codes:
  • 1002 - alias already exists
  • 1003 - invalid alias format
  • 1004 - invalid status
  • 1005 - invalid auth type
  • 1006 - rate not found
  • 1007 - reseller not found
  • 1008 - master status invalid
  • 1009 - master not found
  • 1010 - company not found
  • 1011 - balance invalid
  • 1012 - credit limit invalid
  • 1013 - currency not found
  • 1016 - invalid authentication type

Recharge Account

request_type=recharge_account
Availability: version 1.3.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
Show Top

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
Show Top

Example

You would like to register new user. The incoming data is following:
  • Billing server url: http://192.168.0.1/billing/
  • Remote admin username: registrator
  • Remote admin password: secretpass
  • Alias - 7770777
  • password - 1234567
  • authtype - ANI or calling number
  • status - Enabled
  • rate name - TestRate
  • reseller id - 0
  • Is master - No
  • Master ID - none
  • Company - none
  • Balance - 4.99
  • Currency - USD
  • Creditlimit - 0.00
You will require that Billing System posts back result to following URL:
  • http://192.168.0.3/web/postback
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
  • ratename => TestRate
  • resellerid => 0
  • ismaster => NO
  • masterid => 0
  • companyid => 0
  • balance => 4.99
  • currencyname => USD
  • creditlimit => 0.00
  • require_postback => YES
  • postback_url => http://192.168.0.3/web/postback
Let's construct string for checksum calculation: 
ver=2.0&request_type=add_account&format=1&username=registrator&alias=7
770777&passwd=1234567&authtype=ANI&status=1&ratename=TestRate&reseller
id=0&ismaster=NO&masterid=0&companyid=0&balance=4.99&currencyname=USD&
creditlimit=0.00&require_postback=YES&postback_url=http://192.168.0.3/
web/postback
To calculate signature, we will add password at the end of the string (note tariling &): 
&password=secretpass&
String will look like: 
ver=2.0&request_type=add_account&format=1&username=registrator&alias=7
770777&passwd=1234567&authtype=ANI&status=1&ratename=TestRate&reseller
id=0&ismaster=NO&masterid=0&companyid=0&balance=4.99&currencyname=USD&
creditlimit=0.00&require_postback=YES&postback_url=http://192.168.0.3/
web/postback&password=secretpass&
Now lets get MD5 of the string and bring it uppercase: 
D8A73088A51CE6012D4F169967E1C9D6
Remove password part from it and add key attribute: 
ver=2.0&request_type=add_account&format=1&username=registrator&alias=7
770777&passwd=1234567&authtype=ANI&status=1&ratename=TestRate&reseller
id=0&ismaster=NO&masterid=0&companyid=0&balance=4.99&currencyname=USD&
creditlimit=0.00&require_postback=YES&postback_url=http://192.168.0.3/
web/postback&key=D8A73088A51CE6012D4F169967E1C9D6
finally URL encode values (NOT the entire string!): 
ver=2.0&request_type=add_account&format=1&username=registrator&alias=7
770777&passwd=1234567&authtype=ANI&status=1&ratename=TestRate&
resellerid=0&ismaster=NO&masterid=0&companyid=0&balance=4.99&currencyn
ame=USD&creditlimit=0.00&require_postback=YES&postback_url=http%3A%2F%
2F192.168.0.3%2Fweb%2Fpostback&key=D8A73088A51CE6012D4F169967E1C9D6
The string is ready for sending into Arrow Billing.

Show Top