Next Generation Telephony Systems and Services

Table of Contents

• Introduction
  • Purpose of This Guide
• Principles
  • Request Format
  • List of Supported Request Types
  • Protocol and system level errors
  • Example

Introduction

Purpose of This Guide

Principles

Request format

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.

GET http://hostname/url?ver=\
&format=&request_type=&username=&\
=&...&=&\
require_postback=YES|NO&postback_url=&key= 

• GET - http method
• hostname - fully qualified hostname of Data tech Labs 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.

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

List of Supported Request Types

Get Account Balance

request_type=get_balance

• 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

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

Changes:

    Version 1.4.2: Added return attributes DEST_NAME and MIN_DUR.

    Vesrion 1.4.3: Added request attribute access_dnis.

    Version 1.7.0: Added return attribute ROUTING_GROUP.

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
• 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

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

• 1001 - account not found
• 1014 - destination number not received
• 1015 - rate not found

Update Account

request_type=update_account

• 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
• 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

• Returns message OK if successful or Error Code if failed

• 1016 - could not find or no permission to execute
• 1031 - other errors

Add New Account

request_type=add_account

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

• ACCOUNT_ID - new account ID

• 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

• account_alias - account Alias (username, phone number or H323ID)
• recharge_pin - digits of recharge PIN

• AMOUNT - Amount which was credited to account
• CURRENCY_ID - Recharged Currency ID
• CURRENCY_ID - Recharged Currency ID

• 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 1.5.9 and higher, version 1.7.0 and higher. This function does not exist in versions 1.6.x.

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

Attributes sent:

• no input attributes

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

• None

Get List of Accounts In the Account Group

request_type=get_accounts_from_group

Availability: version 1.5.9 and higher, version 1.7.0 and higher. This function does not exist in versions 1.6.x.

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 

• List of all accounts and passowrds. Fields delimited by pipe (|). Rows delimited by newline ( \n ).

• 1021 - account group not found

Get Speed Dial Numbers

request_type=get_spdial

Availability: version 1.7.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)

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

• 1001 - account not found

Set Speed Dial Number

request_type=set_spdial

Availability: version 1.7.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.

• 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

• 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

• http://192.168.0.3/web/postback

• 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

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&

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&

D8A73088A51CE6012D4F169967E1C9D6

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

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

---