PortaSwitch Interfaces MR47

7/23/2019 PortaSwitch Interfaces MR47

1/391

PORTA

ONE

PortaSwitch

Maintenance

Release

47

External Interfaces

Guide Documentation


2/391

Porta Switch PortaSwitch External System Interfaces

2000-2015 PortaOne, Inc. All rights Reserved. www.portaone.com 2

Copyright Notice & Disclaimers

Copyright 20002015 PortaOne, Inc. All rights reserved

PortaSwitch External Systems Interfaces, April 2015Maintenance Release 47V1.47.06

Please address your comments and suggestions to: Sales Department,PortaOne, Inc. Suite #408, 2963 Glen Drive, Coquitlam BC V3B 2P7Canada.

Changes may be made periodically to the information in this publication.The changes will be incorporated in new editions of the guide. Thesoftware described in this document is furnished under a license

agreement, and may be used or copied only in accordance with the termsthereof. It is against the law to copy the software on any other medium,except as specifically provided in the license agreement. The licensee maymake one copy of the software for backup purposes. No part of thispublication may be reproduced, stored in a retrieval system, or transmittedin any form or by any means, electronic, mechanical, photocopied,recorded or otherwise, without the prior written permission of PortaOneInc.

The software license and limited warranty for the accompanying productsare set forth in the information packet supplied with the product, and are

incorporated herein by this reference. If you cannot locate the softwarelicense, contact your PortaOne representative for a copy.

All product names mentioned in this manual are for identificationpurposes only, and are either trademarks or registered trademarks of theirrespective owners.


3/391



Table of Contents

Preface ............................................................................................................................ 5

Whats New in Maintenance Release 47? ........................................................... 6

1. PortaBilling RADIUS Interface................................................. 8

RADIUS Protocol .......................................................................................................... 9Required RADIUS Attributes.................................................................................... 9

PortaBilling Custom Attributes.......................................................................... 11

RADIUS Return Codes ............................................................................................. 21

2. PortaBilling API .......................................................................... 23

Overview....................................................................................................................... 24

Security ......................................................................................................................... 25

XML API ........................................................................................................................ 25

JSON API ...................................................................................................................... 26

Examples ...................................................................................................................... 27

WSDL ............................................................................................................................. 27

Establishing Authenticated Session .................................................................... 28Global Methods and Types..................................................................................... 31

Access to User Information ................................................................................... 37

Access to Currency Information........................................................................... 41

Access to Destination Information...................................................................... 45

Access to Tariff Information.................................................................................. 54

Access to Environment Information ................................................................... 62

Access to Customer Information ......................................................................... 65

Access to Account Information........................................................................... 140

Access to Node Information................................................................................ 199

Access to DID Inventory Information .............................................................. 201

Access to DID Provider Interface ...................................................................... 210

Access to UA Inventory Information ................................................................ 216Access to UA Profile Generator Information.................................................. 218

Access to Product Information ........................................................................... 219

Access to Subscription Information.................................................................. 240

Access to Rate Information ................................................................................. 242

Access to Representative Information............................................................. 248

Access to Invoice Information............................................................................ 250

Access to Customer Class Information............................................................ 255

Access to Discount Plan Information ............................................................... 260

Access to Brandpane Information..................................................................... 270

Access to Dialing Rule Information................................................................... 271

Access to Routing Plan Information ................................................................. 275

Access to Service Features Information.......................................................... 284Access to Service Information............................................................................ 286

Access to OLI (Originating line information)................................................. 288

Access to Billing Session Information .............................................................. 290

Access to ACL Information................................................................................... 292

Access to Payment Methods and Transactions ............................................ 295

Access to Vendor Information ............................................................................ 299

Access to TransferTo Information..................................................................... 313

Access to AuthzRule Information ...................................................................... 317


4/391



3. PortaSIP Media Server API .................................................... 321

Security ....................................................................................................................... 322

Access to XML API .................................................................................................. 322

Access to JSON API ................................................................................................ 322

WSDL ........................................................................................................................... 323

Establishing an Authenticated Session ............................................................ 324

Global Methods and Types................................................................................... 325

Access to Voicemail Settings............................................................................... 326

Access to Folder Preferences and MailBox and Message DisplayOptions ........................................................................................................................ 330

Auto Attendant Configuration............................................................................. 334

Dial Directory Configuration ................................................................................ 340

Conference Configuration..................................................................................... 343

4. Appendices................................................................................. 349

Examples of RADIUS Communication.............................................................. 350

Examples of Scripts for PortaBilling SOAP Communication ................. 356

Examples of Scripts for PortaBilling JSON Communication.................. 367

Examples of API Scripts in Perl, PHP and Python........................................ 369Description of xDR Record Fields ...................................................................... 373

Service Features Methods .................................................................................... 376

Using the service features methods to change the FollowMe settings383

Definition of Time Period.................................................................................. 385

How to Allow ISP Customers to Purchase Extra Quota via API ............. 388

Sample Script for PortaSIP Media Server SOAP Communication....... 388


5/391



Preface

This document provides information for developers who want tointerface their applications or VoIP systems with PortaSwitch.

Where to get the latest version of this guide

The hard copy of this guide is updated upon major releases only, and doesnot always contain the latest material on enhancements that occur in-between minor releases. The online copy of this guide is always up todate, and integrates the latest changes to the product. You can access thelatest copy of this guide at: www.portaone.com/support/documentation/.

Conventions

This publication uses the following conventions:

Commands and keywords are given in boldface

Terminal sessions, console screens, or system file names aredisplayed in fixed width font

The exclamation markdraws your attention to important information oractions.

NOTE:Notes contain helpful suggestions about or references to materials notcontained in this manual.

Timesavermeans that you can save time by taking the action describedhere.

Tips provide information that might help you solve a problem.

Trademarks and Copyrights

PortaBilling, PortaSIP and PortaSwitch are registered trademarks ofPortaOne, Inc.
http://www.portaone.com/support/documentation/http://www.portaone.com/support/documentation/


6/391



Whats New in Maintenance Release 47?

Thevd_topup

method that allows to top up the volume of aservice (e.g. free minutes or gigabytes) provided to acustomer/account with the discount has been added.

The estimate_taxes method that allows to calculate the taxes

for a payment has been added to the Customer Informationand Account Information schemas

The following obsolete methods have been completely removed:

o add_periodical_payment

o update_periodical_payment

o delete_periodical_payment

o get_periodical_payment_info

o

get_periodical_payment_list

o get_services_consuming

o get_cdrs_retail_customer

o get_lines_activesubscriptions

The following methods for managing product groups have beenadded:

o add_group

o update_group

o delete_group

o get_group_list

The subreseller_statusproperty have been added to the

CustomerInfo structure:

The following properties have been added to the XDRInfo structure:

o i_serviceo i_desto bit_flagso call_recording_urlo call_recording_server_url

The following properties have been added to the ProductInfo

structure:o

volume_discount_plan_nameo topup_addono is_usedo end_user_nameo end_user_descriptiono managed_by_usero included_serviceso allowed_products


7/391



o fraud_protectiono addon_effective_fromo addon_effective_too i_product_groupo product_group_name

The following properties have been added to the

CustomerXDRInfo structure:o i_serviceo i_dest

The following methods for managing tariffs by resellers have been

added:

o get_resale_map_list

o get_resale_map_record

o update_resale_map_record

The rollover_info and threshold_shiftproperties have been added to

the FullCounterInfo structure

The addon_effective_fromand a ddon_effective_toproperties have beenadded to the ProductInfo structure

The descriptionproperty in the DestinationGroupInfo structure has become nillable

The inactivity_expire_timeproperty has been added to the

AccountInfo and GenerateAccountsRequest structuresin MR47-1


8/391

Porta Switch PortaBilling RADIUS Interface


1.PortaBillingRADIUS

Interface


9/391



RADIUS Protocol

PortaBilling uses the RADIUS protocol as per Remote AuthenticationDial-In User Service (RADIUS), RFC 2865 and RADIUS Accounting, RFC2866. By default, the PortaBilling RADIUS server listens on port 1812(UDP) for authentication requests and on port 1813 (UDP) foraccounting requests.

RADIUS Attributes

PortaBilling uses a set of Cisco RADIUS VSAs (Vendor-SpecificAttributes). For more information, please refer to the RADIUS Vendor-Specific Attributes Voice Implementation Guide at Cisco website(http://www.cisco.com).

Required RADIUS AttributesTo ensure compatibility with future releases of PortaBilling, it is highlyrecommended that you follow the Cisco guidelines regarding whichattributes must be contained in each authentication or accounting request.For more information, please refer to the RADIUS Vendor-SpecificAttributes Voice Implementation Guide at Cisco website(http://www.cisco.com).

Authentication / Authorization Requests

Currently, the following attributes are required for correct processing ofauthentication / authorization requests:

Attribute Description

NAS-IP-Address Specifies the IP address of the network accessserver that is requesting authentication

User-Name Indicates the name of the user beingauthenticated by the RADIUS server

Password Indicates the users passwordh323-conf-id The unique call identifier generated by the

gateway. Used to identify the separate billable

events (calls) within a single calling sessionCalled-Station-Id The telephone number the user called. Only for

authorization requestsh323-ivr-out User-definable AV pairs sent from the NAS to

the RADIUS serverMessage-Authenticator Used to authenticate and protect the integrity of

Access-Requests in order to prevent spoofing.
http://www.ietf.org/rfc/rfc2865.txt?number=2865http://www.ietf.org/rfc/rfc2865.txt?number=2865http://www.ietf.org/rfc/rfc2866.txt?number=2866http://www.ietf.org/rfc/rfc2866.txt?number=2866http://www.cisco.com/http://www.cisco.com/http://www.cisco.com/http://www.cisco.com/http://www.cisco.com/http://www.cisco.com/http://www.cisco.com/http://www.cisco.com/http://www.ietf.org/rfc/rfc2866.txt?number=2866http://www.ietf.org/rfc/rfc2866.txt?number=2866http://www.ietf.org/rfc/rfc2865.txt?number=2865http://www.ietf.org/rfc/rfc2865.txt?number=2865


10/391



Authentication / Authorization Responses

Currently, the following standard attributes are used (A1 = authentication,A2 = authorization):

Attribute A1 A2 Descriptionh323-billing-model Y Type of billing service for aspecific session

h323-return-code Y Y Return codes are the serversinstructions to the network accessserver. The list of possible valuesare described in the RADIUSReturn Codessection

h323-currency Y Y Currency used with h323-credit-amount

h323-preferred-lang Y Y Language to use for the audioprompt

h323-credit-amount Y Amount of credit (in currency) inthe account

h323-redirect-number Y OptionalPhone number to which the call isredirected

Message-Authenticator

Y Y Used to authenticate and protectthe integrity of Access-Requestsin order to prevent spoofing.

Accounting Requests

Currently, the following attributes are required for correct processing ofaccounting requests:

Attribute Description

NAS-IP-Address Specifies the IP address of the network accessserver that is sending accounting requests

NAS-Port-Name Indicates the name of the physical NAS portthat is authenticating the user

User-Name Indicates the name of the user for theaccounting request

Calling-Station-Id The telephone number the call came fromCalled-Station-Id The telephone number the user calledh323-setup-time Indicates the setup time in NTP format: hour,

minutes, seconds, microseconds, time_zone,day, month, day_of_month, year


11/391



h323-connect-time Indicates the connect time in Network TimeProtocol (NTP) format: hour, minutes, seconds,microseconds, time_zone, day, month,day_of_month, and year

h323-disconnect-time Indicates the disconnect time in NTP format:hour, minutes, seconds, microseconds,

time_zone, day, month, day_of_month, yearh323-conf-id The unique call identifier generated by the

gateway. Used to identify the separate billableevents (calls) within a single calling session

h323-incoming-conf-id The unique number for identifying a callingsession on a NAS, where a session is closedwhen the calling party hangs up. The h323-incoming-conf-id number is used to:

Match the outbound and inbound calllegs for a session on a particular NAS

Collect and match all records formultiple calls placed (within the boundsof a session) on the gateway

h323-disconnect-cause Specifies the reason a call was disconnectedh323-call-origin The NASes behavior in relation to the

connection that is active for this leg.For example, answer on leg 1; originate on leg 2

h323-call-type Protocol type or family used on this leg of thecall

Acct-Session-Time Indicates how long (in seconds) the user has

received serviceAcct-Status-Type Indicates whether this Accounting-Request

marks the beginning of the user service (Start)or the end Stop)

h323-ivr-out User-definable AV pairs sent from the NAS tothe RADIUS server

h323-remote-address IP address of the remote voice equipment

PortaBilling Custom Attributes

All custom attributes conform to the VSA syntax. Attributes received byPortaBilling are entered into the h323-ivr-outattribute (VSA No. 1),encoded as name:valuepairs. Attributes sent by PortaBilling are enteredinto the h323-ivr-inattribute (VSA No. 1), encoded as name:valuepairs.Unless otherwise specified, any custom attribute may only be includedonce for each request.


12/391



Attributes Sent by a RADIUS Client

(Gateway) to the PortaBilling Server

PortaBilling_Session

This allows you to control an accounts login session (sessions are used toprevent simultaneous logins by debit accounts). This attribute may beused in the accounting record for a specific call leg in order to force thesession to be unlocked. (For instance, to force a session unlock on theanswer/VoIP call leg, instead of the customary answer/Telephony callleg). An optional expiresparameter may control how long the sessionlock state is supposed to be held on BE (for example, to preserve thefunds deposited for the session until the next radius message.)

Format:PortaBilling_Session:PortaBilling_Session:lock=[;expires=]

Possible lock values:

Value Description

nolock Do not lock the account after the current requestunlock Do not lock the account for the current session and unlock

any other existing session for this accountrelock Lock the account for the current session and unlock any

other existing session for this accountignore Do not set or remove any locks, and skip any lock checks

Example:h323-ivr-out = 'PortaBilling_Session:nolock'

PortaBilling_Ignore_Password

This allows the password check during authentication or authorization tobe disabled.

Format:PortaBilling_Ignore_Password:

Possible values:YES or NO.

Example:h323-ivr-out = PortaBilling_Ignore_Password:YES'


13/391



PortaBilling_CallbackHistory

This provides information about the other (second) call leg of a call, sothat the first call leg can be billed properly (e.g. do not bill the first leg ifthe second leg was not connected).This attribute may be present multiple times in a request. Only the last

occurrence is actually used, while the others are ignored.

Format:PortaBilling_CallbackHistory:

Possible values:Value Description

START The first call leg was startedATTEMPT The callback engine attempted to establish an outgoing call

for the second legOK The second call leg was successfully connected

If there is no OK entry, the call leg will be billed using a special rate planassociated in the product configuration with the CALLBACK_FAILaccess code.

Example:h323-ivr-out = 'PortaBilling_CallbackHistory:START'h323-ivr-out = 'PortaBilling_CallbackHistory:ATTEMPT'h323-ivr-out = 'PortaBilling_CallbackHistory:OK'

PortaBilling_AccessCode

An access code for selecting a specific rate plan within a product.

Although originally used to pass the IVR access number to billing, itmay contain any string (e.g. FIRSTCALL). For Quintum compatibility,this attribute also has the synonym ACCESSCODE.

Format:PortaBilling_AccessCode:

Possible values:Any string. The value passed will be compared to the values entered in theproducts accessibility (case-sensitively).

Example:h323-ivr-out = 'PortaBilling_AccessCode:18001234567'

PortaBilling_Original_DNIS

This replaces the value of the Called-Station-Id attribute (i.e. thedestination phone number used for call rating).


14/391



Format:PortaBilling_Original_DNIS:

where the value is a semicolon-separated list of name:valuepairs.

Possible values:E.164 phone number (a sequence of digits, * and/or # signs).

Example:h323-ivr-out = 'PortaBilling_Original_DNIS:19001234567'

PortaBilling_RestoreCacheLevel

This controls how the billing engine uses the account informationretrieved during the authorization process for a request, in order tofacilitate the processing of other requests. Its most common application isto disable this information for re-use, if for some reason informationfrom the current request should not be applied to other call legs (e.g. incallback scripts).

Format:PortaBilling_RestoreCacheLevel:

Possible values:Value Description

-1 Disable caching and reuse of account information.0 Use the default policy.

Example:h323-ivr-out = ' PortaBilling_RestoreCacheLevel:-1'

PortaOne-Service-Type (formerly Service-Identifier)

This contains the identifier for a service in PortaBilling.

Format:PortaOne-Service-Type=

Possible values:A non-empty string identifying a service in PortaBilling:

Session Generic time-based service type; it can be used to applycharges for any service use based on the length of time the service

was accessed. Voice Rating telephony calls (incoming or outgoing) made via

PortaSIP, VoIP gateways or other equipment.

Data Data transfers rated using the amount transferred as thebilling parameter.

Netaccess Internet access sessions (DSL, PPPoE, etc.), ratedbased on session duration or the amount of transferred data.


15/391



Quantity Generic quantity-based service type; can be used toapply charges for any service use expressible in numerical form(e.g. the number of pizzas ordered).

Wifi Wireless Internet access sessions, rated based on sessionduration.

Dialup Dialup Internet access sessions, rated based on sessionduration.

Msg Rating messages (text, SMS, MMS, other) based on thenumber of messages sent.

Conference Rating conference calls via PortaSIP Media Server(or some conferencing server).

Did Can be used to apply charges to customers for usage ofDID numbers.

Example:PortaOne-Service-Type=Conference

PortaOne-Calling-Party

This provides information about the calling party.

Format:PortaOne-Calling-Party:;

Properties:

Possible values:Property Description

id This contains the caller ID information for the call. It istaken from the P-Asserted-Identity andRPIDheadersdisplay-id This indicates the Caller number value

that is taken from the From: header and typicallydisplayed on the called partys phone display

privacy This is a privacy flag which indicates that the calling partyrequests its identification to be kept private (hidden fromthe final call recipient.) Possible values: 1/0, default 0

name This is a caller name. It is taken from the CLN fieldx-id The callers extension number configured on the PBX of a

calling partyctx-id The unique identifier for the calling party PBX

Example:h323-ivr-out = 'PortaOne-Calling-Party = 'ctx-id=52333;name=EASYCALL;id=17289277770;display-id=17289277770''


16/391



PortaOne-Redirecting-Party

This provides information about the redirecting party in case the call isforwarded or transferred.

Format:

PortaOne-Redirecting-Party:;

The properties and values are the same as for the PortaOne-Calling-Partyattribute described above.

Used-Service-Unit

This specifies the amount of used service units there are, measured fromthe point when the service session identified in the h323_conf_id attributebecame active.

Format:

Used-Service-Unit:

Possible values:Integer number specifying amount of measurement units.

Example:h323-ivr-out = Used-Service-Unit:222

Attributes Sent by the PortaBilling Server

to a RADIUS Client (Gateway)

Attribute A1 A2 DescriptionDURATION Y The maximum allowed

call duration (in seconds)Tariff Y Y The name of the rate plan

applied to the accountwithin this session

available-funds Y For debit accounts, this isequal to the h323-credit-amount. For creditaccounts, this returns theactual amount of available

funds (the differencebetween the credit limitand the current balancewith respect to the creditlimits for the individualaccount and customer)

h323-preferred-lang Y Y Language preference forthe audio prompt


17/391



h323-credit-amount Y Amount of credit (incurrency) in the account

h323-credit-time Y Amount of seconds forwhich the call isauthorized

PortaBilling_UserName Y Y The account ID to beused for billing this call

PortaBilling_RatePattern Y The rate pattern is a stringused by PortaBilling tomatch the correspondingrate code/destinationduring authorization of anaccount, instead of theCalled-Station-Id

PortaBilling_AccessCode Y Y Access code to be usedfor matching rating entryand tariff

PortaBilling_AccountBalance Y The current amount ofthe accounts balance inPortaBilling

PortaBilling_CustomerBalance Y The current amount ofthe customers balance inPortaBilling

PortaBilling_CustomerCreditLimit Y The customers currentcredit limit inPortaBilling

PortaBilling_CustomerCreditLimitThreshold

Y The customers currentbalance warning in

PortaBillingBalanceThreshold Y Indicates that a customers

balance warning thresholdhas been reached

PortaBilling_ProductBreakage Y The breakage amount ofthe accounts product inPortaBilling

PortaBilling_No_Disconnect_Warning

Y Indicates that NAS wontplay a time left warning(the remaining timeannouncement in

seconds or a beepingsound) when a specifiednumber of seconds is leftbefore the call isdisconnected (calls will beterminated silently)


18/391



DURATION

This specifies the real allowed maximum call duration (in seconds), whichmay differ from the announced credit time if billing tricks are applied.

Format:

DURATION:

Possible values:Positive integer (number of seconds).

Example:h323-ivr-in = 'DURATION:320'

Tariff

The name of the rate plan applied to the account within this session.

Format:Tariff:

Possible values:Positive integer (number of seconds).

Example:h323-ivr-in = 'Tariff:ABC prepaid'

Available-funds

For debit accounts, this is equal to the h323-credit-amount. For creditaccounts, this returns the actual amount of available funds (the differencebetween the credit limit and the current balance with respect to the creditlimits for the individual account and customer).

Format:available-funds:

Possible values:Any positive number formatted with two decimal places; a dot (.) is usedas the decimal separator.

Example:

h323-ivr-in = ' available-funds:124.78'

PortaBilling_UserName

The account ID to be used for billing this call. The RADIUS client mustsupply this value as the User-Name(or, alternatively, in h323-ivr-out=PortaBilling_UserName) attribute value in the accounting records forall call legs (incoming and outgoing).


19/391



Format:PortaBilling_UserName:

Possible values:A non-empty string identifying an account in PortaBilling.

Example:h323-ivr-in = 'PortaBilling_UserName:16051233355'

PortaBilling_RatePattern

The rate pattern is a string used by PortaBilling to match thecorresponding rate code/destination during authorization of an account,instead of the Called-Station-Id (e.g. when a customer is to be billedaccording to a special rate such as VOICEONNET, rather than accordingto the actual number dialed). The RADIUS client mustsupply this valueas the h323-ivr-out=PortaBilling_RatePatternattribute value in theaccounting records for all outgoing legs of this call.

Format:PortaBilling_RatePattern :

Possible values:A non-empty string, usually a destination number in e.164 format.

Example:h323-ivr-in = 'PortaBilling_RatePattern:18001233355'

PortaBilling_AccessCode

The string actually used by PortaBilling to match the correspondingaccessibility entry and tariff. NAS should copy this value into all futurecall accounting requests as h323-ivr-out=PortaBilling_AccessCode, inorder to apply the same properties during billing.

Format:PortaBilling_AccessCode:

Possible values:A non-empty string, the same as for h323-ivr-out=PortaBilling_AccessCode.

Example:h323-ivr-in = 'PortaBilling_AccessCode:18001234567'

PortaBilling_AccountBalance

The current amount of the accounts balance in PortaBilling.

Format:PortaBilling_AccountBalance:


20/391



Possible values:A number with a precision of five decimal places.

Example:h323-ivr-in = 'PortaBilling_AccountBalance:13.20000'

PortaBilling_CustomerBalance

The current amount of the customers balance in PortaBilling.

Format:PortaBilling_CustomerBalance:


Example:

h323-ivr-in = 'PortaBilling_CurstomerBalance:13.20000'

PortaBilling_CustomerCreditLimit

The current amount of the customers credit limit in PortaBilling.

Format:PortaBilling_CustomerCreditLimit:


Example:h323-ivr-in = 'PortaBilling_CustomerCreditLimit:13.00000'

PortaBilling_CustomerCreditLimitThreshold

The current amount of the customers credit limit threshold inPortaBilling. Note that the relative threshold limit is converted into anactual currency amount.

Format:PortaBilling_CustomerCreditLimitThreshold:


Example:h323-ivr-in ='PortaBilling_CustomerCreditLimitThreshold:12.00000'


21/391



BalanceThreshold

Indicates that the customers balance warning threshold has been reached.

Format:BalanceThreshold:

Possible values:YES

Example:h323-ivr-in = BalanceThreshold:YES'

PortaBilling_ProductBreakage

The breakage amount of the accounts product in PortaBilling.

Format:PortaBilling_ProductBreakage:


Example:h323-ivr-in = 'PortaBilling_ProductBreakage:0.02000'

PortaBilling_No_Disconnect_Warning

Indicates that NAS should cancel IVR/beep warnings before call sessiontimeouts (calls will be terminated silently).

Format:PortaBilling_No_Disconnect_Warning:

Possible values:YES

Example:h323-ivr-in = PortaBilling_No_Disconnect_Warning:YES'

RADIUS Return Codes

Return codes can be defined by the user through the implementation ofthe IVR script and RADIUS server agreement. The following table liststhe return codes that are predefined and anticipated by existing Cisco IVRscripts.


22/391



Explanation

codeh323-return-code

Description

success 0 Success, proceedinvalid_account 1 Failed - Invalid Account numberinvalid_password 2 Failed - Invalid Passwordaccount_in_use 3 Failed - Account in usezero_balance 4 Failed - Zero balancecard_expired 5 Failed - Card expiredcredit_limit 6 Failed - Credit limituser_denied 7 Failed - User deniednot_available 8 Failed - Service not availablecld_blocked 9 Failed - Called number blockedretries_exceeded 10 Failed - Number of retries

exceededinvalid_argument 11 Failed - Invalid argument

insuff_balance 12 Failed - Insufficient balancetoll_free_allowed 13 Toll-free calls allowedinvalid_card 14 Failed - Invalid card numberhairpin_to_pstn 50 Call will be hairpinned back to the

Public Switched TelephoneNetwork (PSTN)

redirect 51 Redirect to called party (useredirect number)

redirect_to_cs 52 Redirect to customer Service (useredirect number)


23/391

Porta Switch PortaBilling API


2.PortaBilling API


24/391



Overview

PortaBilling allows you to perform operations such as data retrieval ordata modification via API using the following Web Application Services:XML (SOAP) and JSON RPC.

BillingPorta

XML/JSON

API

Reseller of A(Environment A)

Application

ITSP A(Environment A)

Application X

ITSP B(Environment B)

Application Y

HTTPS

Performing operations via API has several advantages:

It is based on either XML/SOAP (Simple Object AccessProtocol) or JSON (JavaScript Object Notation) Web ApplicationServices and HTTPS transport, so it is accessible from anyplatform or operating system, and all communication between the

server and clients is secure. The business logic embedded into the API provides integrity

checks for all data modifications, and can compile records fromseveral database tables to create a single customer informationretrieval structure.

PortaBilling API is accessible to every owner of a virtual

environment or reseller. Each users access is automatically limitedto his visible portion of the available data, e.g. a reseller can onlyretrieve information about his own sub-customers or theiraccounts.

PortaBilling API allows users to perform select, update, insert or deleteoperations on entities such as customers or accounts. Each user has hisown login credentials, and each operation he wishes to perform isanalyzed to determine if it is possible with regard to general data integrity(e.g. a new account cannot be created without being assigned to acustomer) as well as the given users security permissions (ACLs) (e.g.while it is generally possible to create new accounts, a certain user may beprohibited from doing so).


25/391



Security

Connection to the API interface is provided via HTTPS. Authentication isdone using a pair: a user login and either the API access token or the userpassword for the administrative web interface. Each request to the API

should contain theAuthInfoStructurestructure as the header attribute.Note that we strongly recommend using the session_id property (whichmust be received during the authorization via the loginrequest) in theAuthInfoStructurestructure for all session requests. Otherwise, if youuse the login-password or the API access token authentication pairs forevery request, new sessions will be created and cause additional load tothe database.

XML API

XML/SOAP API has its own advantages and drawbacks as comparedwith JSON API. Among the benefits are the following:

There is a wide range of reusable software available to

programmers to handle XML so they dont have to re-inventcode.

XML/SOAP is more verbose compared with JSON, but becauseof this, the data encoding result is typically larger than theequivalent encoding in JSON API.

Access to XML API

All SOAP requests to PortaBilling API must be sent to the followingURL: https://portabilling-web.yourdomain.com:/soap/

Please replace theportabilling-web.yourdomain.com with the actualhostname of your PortaBilling web server.

Replace with the required port. The SOAP interface is availablefor administrators on port 443, the interface for customers is available onport 8444, the interface for resellers is available on port 8442 and theinterface for accounts is available on port 8445.

Error HandlingSOAP faults are used to carry error information within a SOAP message.If the actual response has a SOAP fault element as the body entry, then anerror has occurred. In this case, any other fields in the response cannot beguaranteed as accurate; only the fault sub-elements should be used toidentify an error. Currently, these sub-elements are:


26/391



faultcode is intended for use by the client software and providesan algorithmic mechanism for identifying the fault;

faultstring provides a human readable explanation of the fault,and is not intended for algorithmic processing.

JSON API

As an alternative to XML API, PortaBillling supports JSON API, thusproviding your development department with a choice of WebApplication Services that can be used. Among the advantages of JSONAPI are the following:

Simple data structures that can be easily read and written;

JSON format is faster in parsing and generating data due tosimple syntax, thus there is little influence on web serverperformance;

Supports the same methods as those in the SOAP;

Simplifies the creation of front-end web sites that receive andmodify data in PortaBilling with minimum impact onperformance.

Access to JSON API

All JSON requests to PortaBilling API must be sent to the followingURL: https://:/rest///

Please replace theportabilling-web.yourdomain.com with the actual

hostname of your PortaBilling web server.

Replace with the required port. The JSON interface is availablefor administrators on port 443, the interface for customers is available onport 8444, the interface for resellers is available on port 8442 and theinterface for accounts is available on port 8445.

Replace with the API service that contains the requiredmethod (e.g. specify theAccountservice to manage accountinformation.)

Replace with the required API method (e.g. specifyget_account_infomethod in order to get an account record from thedatabase.)

Here is an example of the URL the POST request to be sent to:

https://demo.portaone.com:443/rest/Account/get_account_info/


27/391



Sending an HTTP request

For HTTP requests you must include the following parameters (in JSONformat) in the POST request body:

auth_info The mandatory authentication information (see the

Securitysection);

params A set of method parameters (in JSON format) thatdepend on a method structure. Note that method parameters andtheir structures are the same as those in the SOAP;

Error Handling

If the server returns the 500 Internal Server Error status code in theHTTP response, then the response body contains a JSON object whichincludes two elements (keys) that carry error information:

faultcode, that is intended for use by the client software andprovides an algorithmic mechanism for identifying the fault;

faultstring, that provides a human readable explanation of thefault, and is not intended for algorithmic processing.

Examples

You can find code samples for Perl for both XML (SOAP) and JSONformats in the Appendices to the guide.

WSDLEach installation of PortaBilling contains its own set of WSDLdocuments available for download from the web server from thefollowing URL:https://portabilling-web.yourdomain.com/wsdl/

Please replace theportabilling-web.yourdomain.com with the actualhostname of your PortaBilling web server.

All requests to PortaBilling API are handled via an SSL connection. Bydefault, PortaBilling installations contain a self-signed certificate that

provides the means to encrypt data. However, since the authenticity ofthis certificate cannot be validated, you may experience some problemswhen connecting to an SSL site. In this case, it may be necessary to obtaina certificate from a genuine certificate authority. Another option is togenerate your own certificate authority and have certificates deployed toall API clients. However, this goes beyond the scope of the presentdocument.


28/391



Notation conventions

The following typographic conventions apply throughout this chapter:

* A value can be entered for this property only when insertingnew records and cannot be changed later.

** This property is read-only, and its value cannot be changed.

Mandatory properties (whose value must be entered duringinsertion, and cannot be set to an empty value later) areunderlined.

n This property can be used with the nilattribute to indicate thatit is blank (has no content):

o In the Requestmessage the xsi:nil=true attribute can beused to clear the property (set value to NULL in thedatabase).

o In the Responsemessage a property has the xsi:nil=trueattribute if it is blank (has the NULL value in thedatabase).

Establishing Authenticated Session

SOAP URI (namespace): https://portabilling-web.yourdomain.com/Porta/SOAP/Session

Methods

login

Parameters:LoginRequestReturn value:LoginResponse

Checks the validity of login and password or token and returns session_idon success. API Fault is thrown on failure.

ping

Parameters: PingRequestReturn value: PingResponse

Checks the validity of previously opened session and returns user_id

on success. API Fault is thrown on failure.

logout

Parameters:LogoutRequestReturn value: no value is returned on success


29/391



Terminates a session. You should call logout() to terminate the sessionproperly.

reset_password

Parameters: ResetPasswordRequest

Return value: ResetPasswordResponseRealm: administrator, reseller, retail customer, account, cc staff

Allows an API user to reset the password and create a new one.

Type Reference

HeaderRequest structure

Property Type Description

auth_info AuthInfoStructure The user login for PortaBilling

web interface

AuthInfoStructure structure


login string, 16 chars max The user login for PortaBillingweb interface

and one of the following two:password string, 16 chars max The user password for

PortaBilling web interfaceor:token string The API access token of a user

Note that the token can only beused for the administrativeinterface (the admin realm)

or alternatively (used without the login):session_id string, 32 chars max The unique ID of a previously

opened SOAP session

LoginRequest structure


login string User Name, as specified on webinterface

and one of the following two:password string Password, as specified on web

interfacetoken string The API access token of a user

Note that the token can only be


30/391



used for the administrativeinterface (the admin realm)

LoginResponse structure


session_id string, 32 charsmax

The unique ID of the newlyopened session

PingRequest structure


session_id string ID of previously opened session

PingResponse structure


user_id int ID of user currently logged in to

the specified session

LogoutRequest structure


session_id string ID of previously opened session

ResetPasswordRequest structure


login string The user login for thePortaBilling web interface

email string The user email addresscustom_url string Optional link to the reset

password page. If not suppliedthen the default PortaBillingforgot password page url willbe sent

id string The reset password IDpassword string A new password

ResetPasswordResponse structure

Property Type Descriptionsuccess int 1 in case of success, 0 in case of

failure


31/391



Global Methods and Types

SOAP URI (namespace): https://portabilling-web.yourdomain.com/Porta/SOAP/Generic

Methods

get_version

Parameters: GetVersionRequestReturn value: GetVersionResponse Realm: administrator

This method allows an API user to get the version of PortaBillingversion.

get_countries_list

Parameters: GetCountriesListRequestReturn value: GetCountriesListResponseRealm: administrator, reseller, retail customer, account

This method allows an API user to get the list of countries.

get_subdivisions_list

Parameters: GetSubdivisionsListRequestReturn value: GetSubdivisionsListResponseRealm: administrator, reseller, retail customer, account

This method allows an API user to get the list of country subdivisions fora specific counry.

Global Information (Currencies)

get_global_currency_list

Parameters: GetGlobalCurrencyListRequestReturn value: GetGlobalCurrencyListResponseRealm: administrator, reseller, retail customer, account

This method allows an API user to get information about all actual andoutdated world currencies.

get_global_currency_info

Parameters: GetGlobalCurrencyInfoRequestReturn value: GetGlobalCurrencyInfoResponseRealm: administrator, reseller, retail customer, account


32/391



This method allows an API user to get information about a specific globalcurrency.

Global Information (Exchange Rates)

get_exchange_rate_list

Parameters: GetXrateListRequestReturn value: GetXrateListResponseRealm: administrator

This method allows an API user to get a list of all exchange rates usedwithin the system.

Global Information (Time Zone)

get_time_zone_list

Parameters: GetTimeZoneListRequestReturn value: GetTimeZoneListResponseRealm: administrator, reseller, retail customer, account

This method allows an API user to get information about time zones.

get_time_zone_info

Parameters: GetTimeZoneInfoRequestReturn value: GetTimeZoneInfoResponse

Realm: administrator, reseller, retail customer, account

This method allows an API user to get information about a specific timezone.

Global Information (Billing Periods)

get_billing_period_list

Parameters: GetBillingPeriodListRequestReturn value: GetBillingPeriodListResponse

Realm: administrator, reseller

This method allows an API user to get information about billing periods.


33/391



Type Reference

GetVersionRequest structure

Does not include any properties

GetVersionResponse structure


version n string PortaBilling version

GetCountriesListRequest structure


GetCountriesListResponse structure


countries_list n Array ofCountryInfo

Set of country data records

CountryInfo structure


iso_3166_1_a2 string A two-letter country code defined inISO 3166-1 alpha-2

name string Country name

GetSubdivisionsListRequest structure

Property Type Descriptioniso_3166_1_a2 string A two-letter country code defined

in ISO 3166-1 alpha-2

GetSubdivisionsListResponse structure


subdivisions_list n Array ofSubdivisionInfo

Set of country subdivision datarecords

SubdivisionInfo structure


i_country_subdivision int A unique ID of countrysubdivision

name string Subdivision nameiso_3166_1_a2 string A two-letter country code

defined in ISO 3166-1 alpha-2


34/391



iso_3166_2 string A code of a principalsubdivision (e.g. provinceorstate)

Type Reference (Currencies)

GetGlobalCurrencyListRequest structure


obsolete string Specifies what currency to fetch.Possible values are:

all

actual

obsolete

GetGlobalCurrencyListResponse structure

Property Type Descriptionglobal_currency_list n Array of

GlobalCurrencyInfo structures

List of global currencies

GlobalCurrencyInfo structure


name string The currency nameiso_4217 string ISO4217 alphabetic code, the unique

currency identifier

iso_4217_num string ISO4217 numeric code, the uniquecurrency identifierdecimal_digits int Maximum number of decimal places

allowed by the currency, e.g.for US dollars or euros it will be 2, sincethe smallest unit is one cent (0.01),while for yen it will be 0, becausean amount in yens can only be aninteger

name_major ** string Major name of the currency, e.g. dollar(returned only in the response to the"get" method)

name_minor ** string Minor name of the currency, e.g. cent,(returned only in the response to theget method)

obsolete string,Y/N

Specifies whether this currency isobsolete
http://en.wikipedia.org/wiki/Provincehttp://en.wikipedia.org/wiki/State_%28administrative_division%29http://en.wikipedia.org/wiki/State_%28administrative_division%29http://en.wikipedia.org/wiki/Province


35/391



GetGlobalCurrencyInfoRequest structure


iso_4217 string ISO4217 alphabetic code, theunique currency identifier

GetGlobalCurrencyInfoResponse structure


global_currency_info GlobalCurrencyInfostructure

Complete information aboutthe global currency. Seeabove for more detail

Type Reference (Exchange Rates)

GetXrateListRequest structure


iso_4217 stringSpecifies the currency in ISO4217code for which to provide exchangerates

only_active intSpecifies whether to show onlyactive exchange rates

limit int Number of exchange rates toretrieve

offset int Number of rows to skip at thebeginning of the list

get_total int Get total number of the retrievedexchange rates

GetXrateListResponse structure


exchange_rate_listArray of XrateInfostructures

total intTotal number of theretrieved exchange rate datarecords

XrateInfo structure


source** stringShows the exchange rate source for thegiven currency as defined on the Currencypage

timestamp** dateTimeThe effective date for the given exchangerate


36/391



iso_4217** stringSpecifies a currency in ISO4217 code (thecurrency to convert to)

name** string A currency name

base_iso_4217** stringShows a base currency in ISO4217 code (acurrency to convert from)

base_units** float

Currency exchange rate. Defines thenumber of units of the base currency equalto one unit of the foreign currency. (Forexample, with British Pounds as theforeign currency and U.S. Dollars as thebase currency , the base currency unitswould be 1.5326 and the value of thiscolumn would be 1 GBP = 1.5326)

is_active** int

Specifies whether the exchange rate isusable now

1 the exchange rate is now usable

0 the exchange rate is not usable,e.g. outdated

Type Reference (Time Zone)

GetTimeZoneListRequest structure


search string Pattern that allows to search by atime zone name.

Use the following wildcard symbols:

The percentage ( % )wildcard allows you tomatch any string of zero ormore characters;

The underscore ( _ )wildcard allows you tomatch any single character

GetTimeZoneListResponse structure


time_zone_list Array ofTimeZoneInfostructures

List of time zones.

TimeZoneInfo structure


i_time_zone int The unique ID of the time zone


37/391



time_zone_name string A commonly used name for thetime zone

GetTimeZoneInfoRequest structure


i_time_zone int The unique ID of the time zone

GetTimeZoneInfoResponse structure


time_zone_info n TimeZoneInfostructure

Complete informationabout the time zone. Seeabove for more detail

Type Reference (Billing Periods)

GetBillingPeriodListRequest structure


GetBillingPeriodListResponse structure


billing_period_list Array ofBillingPeriodInfo

The list of billing periods.

BillingPeriodInfo structure

Property Type Descriptioni_billing_period int The unique ID of the billingperiod.

description string The billing period description.

Access to User Information

SOAP URI (namespace): https://portabilling-web.yourdomain.com/Porta/SOAP/User

Methods

get_user_info

Parameters: GetUserInfoRequestReturn value: GetUserInfoResponseRealm: administrator


38/391



This method allows an API user to get information about anadministrative user.

get_user_list

Parameters: GetUserInfoListRequest

Return value: GetUserInfoListResponseRealm: administrator

This method allows an API user to retrieve the list of administrative users.

add_user

Parameters:AddUserRequestReturn value:AddUserResponseRealm: administrator

This method allows an API user to add an administrative user.

update_user

Parameters: UpdateUserRequestReturn value: UpdateUserResponseRealm: administrator

This method allows an API user to update an existing administrative user.

delete_user

Parameters: DeleteUserRequest

Return value: DeleteUserResponseRealm: administrator

This method allows an API user to delete an existing administrative user.

Type Reference for User Information

UserInfo structure


i_user string The unique ID of the user

recordlogin string The username for login and

user identification


39/391



status ** string Indicates users status. Can bethe following:

empty (if the user isactive);

inactive;

expired.password string The password for this userdescription string A short description associated

with the useremail string An e-mail contact for the useractivation_date string The date when the users

account is activatedexpiration_date string The date when the users

account expiresi_time_zone int The time zone in which this

user is operating

out_date_format string Output date formatout_time_format string Output time formatout_date_time_format string Output date and time formatin_date_format string Input date formatin_time_format string Input time formati_acl int The privilege level or role

assigned to the useri_lang string The language used on the

admin web interface for thisuser

companyname string The conventional form of

user companys namesalutation string The users salutationfirstname string The users first namemidinit string The users middle namelastname string The users last namebaddr1 string 1st line of user's addressbaddr2 string 2nd line of user's addressbaddr3 string 3rd line of user's addressbaddr4 string 4th line of user's addressbaddr5 string 5th line of user's addresscity string The name of the city

state string The name of the statezip string Users ZIP codecountry string The name of the countrycont1 string The main contact personphone1 string The main phone numberfaxnum string A fax numberphone2 string An alternative phone numbercont2 string An alternative contact person


40/391



GetUserInfoRequest structure


i_user int The unique ID of the userrecord

GetUserInfoResponse structure


user_info UserInfostructure

Complete information about theuser

GetUserInfoListRequest structure



limit int Number of rows to retrieve

search string Pattern that allows to search byusers personal information(login, company name, first name,last name, baddr1, baddr2, city,zip, cont1, cont2, phone1,phone2, email, description).

Use the following wildcardsymbols:

The percentage ( % )wildcard allows you to

match any string of zeroor more characters;

The underscore ( _ )wildcard allows you tomatch any single character

GetUserInfoListResponse structure


user_list n Array of UserInfostructures

Set of user data records

AddUserRequest structure


user_info UserInfo structure Complete informationabout the user


41/391



AddUserResponse structure


i_user int The unique ID ofthe user record

UpdateUserRequest structure


user_info UserInfo structure Complete informationabout the user

UpdateUserResponse structure


i_user int The unique ID of the userrecord

DeleteUserRequest structure


i_user int The unique ID of the user record

DeleteUserResponse structure


success int 1 in case of success, 0 in case offailure

Access to Currency Information

SOAP URI (namespace): https://portabilling-web.yourdomain.com/Porta/SOAP/Currency

Methods

get_currency_info

Parameters: GetCurrencyInfoRequestReturn value: GetCurrencyInfoResponse


This method allows an API user to get information about a currencycreated in PortaBilling.

get_currency_list

Parameters: GetCurrencyListRequest


42/391



Return value: GetCurrencyListResponseRealm: administrator, reseller, retail customer, account

This method allows an API user to get the list of currencies created inPortaBilling.

add_currency

Parameters:AddCurrencyRequestReturn value:AddCurrencyResponseRealm: administrator, reseller, retail customer, account

This method allows an API user to add a currency.

delete_currency

Parameters: DeleteCurrencyRequestReturn value: DeleteCurrencyResponse


This method allows an API user to delete a currency.

update_currency

Parameters: UpdateCurrencyRequestReturn value: UpdateCurrencyResponseRealm: administrator, reseller, retail customer, account

This method allows an API user to update a currency.

Type Reference

CurrencyInfo structure


iso_4217 string Currency ISO4217 codename string Currency namename_major string The main currency unit, e.g.

dollarname_minor string The lesser currency unit (if

applicable), e.g. centi_x_rate_source int Defines the method of

entering the exchange rate forthis currency. Refers to theX_Rate_Source table


43/391



i_ma_currency int The unique merchant accountcurrency identifier. Thisproperty is mandatoryif min_paymentor i_merchant_account issupplied

i_merchant_account int The unique payment systemID for the transaction

base_units float An exchange rate between thecurrency and base unit. Thisproperty is used for manualexchange only(i_x_rate_source=1 )

min_allowed_payment float The smallest allowed amountfor an online payment (in thecorresponding currency), inorder to prevent service

abuse.

GetCurrencyInfoRequest structure


iso_4217 string Currency ISO4217 codei_ma_currency int The unique merchant account

currency identifier.

GetCurrencyInfoResponse structure


currency_info CurrencyInfostructure

Complete information about theCurrency

GetCurrencyListRequest structure





44/391



search string Pattern that allows to search byCurrency name.

Use the following wildcardsymbols:

The percentage ( % )wildcard allows you tomatch any string of zeroor more characters;

The underscore ( _ )

wildcard allows you tomatch any single character

GetCurrencyListResponse structure


Currency_list Array of

CurrencyInfostructures

Set of Currency data

records

AddCurrencyRequest structure



Complete informationabout the Currency

AddCurrencyResponse structure


iso_4217 string The unique ID ofthe Currency record

i_ma_currency int The unique merchantaccount currencyidentifier

UpdateCurrencyRequest structure



Complete informationabout the Currency

UpdateCurrencyResponse structure


iso_4217 string The unique ID ofthe Currency record

i_ma_currency int The unique merchantaccount currencyidentifier


45/391



DeleteCurrencyRequest structure


iso_4217 string The unique ID of the Currencyrecord

i_ma_currency int The unique merchant account

currency identifier

DeleteCurrencyResponse structure


success int 1 in case of success, 0 in case offailure

Access to Destination Information

SOAP URI (namespace): https://portabilling-web.yourdomain.com/Porta/SOAP/Destination

Methods

get_destination_info

Parameters: GetDestinationPrefixInfoRequestReturn value: GetDestinationPrefixInfoResponseRealm: administrator

This method allows an API user to get information about a destination.

get_destination_list

Parameters: GetDestinationPrefixListRequestReturn value: GetDestinationPrefixListResponseRealm: administrator

This method allows an administrator to retrieve the list of destinations.

match_destination_groups

Parameters: MatchDestinationGroupsRequest

Return value: MatchDestinationGroupsResponseRealm: administrator

This method allows an administrator to locate a destination group bytariff and phone number.


46/391



add_destination

Parameters:AddDestinationPrefixRequestReturn value:AddDestinationPrefixResponseRealm: administrator

This method allows an API user to add a destination.

update_destination

Parameters: UpdateDestinationPrefixRequestReturn value: UpdateDestinationPrefixResponseRealm: administrator

This method allows an API user to update an existing destination.

get_dest_group_set_list

Parameters: GetDestGroupSetListRequestReturn value: GetDestGroupSetListResponseRealm: administrator

This method allows an API user to get a list of destination group sets.

add_dest_group_set

Parameters:AddUpdateDestGroupSetRequestReturn value:AddUpdateDestGroupSetResponseRealm: administrator

This method allows an API user to add a destination group set.

delete_dest_group_set

Parameters: DeleteDestGroupSetRequestReturn value: DeleteDestGroupSetResponse Realm: administrator

This method allows an API user to delete a destination group set.

update_dest_group_set

Parameters: UpdateDestGroupSetRequestReturn value: UpdateDestGroupSetResponseRealm: administrator

This method allows an API user to update a destination group set.


47/391



get_dest_group_list

Parameters: GetDestGroupListRequestReturn value: GetDestGroupListResponseRealm: administrator

This method allows an API user to get a list of destination groups.

add_dest_group

Parameters:AddDestGroupRequestReturn value:AddDestGroupResponseRealm: administrator

This method allows an API user to add a destination group.

delete_dest_group

Parameters: DeleteDestGroupRequestReturn value: DeleteDestGroupResponseRealm: administrator

This method allows an API user to delete a destination group.

update_dest_group

Parameters: UpdateDestGroupRequestReturn value: UpdateDestGroupResponseRealm: administrator

This method allows an API user to update an existing destination group.

get_dest_group_info

Parameters: GetDestGroupInfoRequestReturn value: GetDestGroupInfoResponseRealm: administrator

This method allows an API user to get information about a destinationgroup.

Type Reference

AddDestinationPrefixRequest structure


destination_info DestinationPrefixInfostructure

Complete informationabout the destination; formore information, seebelow


48/391



AddDestinationPrefixResponse structure


i_dest int The unique ID ofa destination record

UpdateDestinationPrefixRequest structure


destination_info DestinationPrefixInfostructure

Complete informationabout the destination; formore information, seebelow

UpdateDestinationPrefixResponse structure


i_dest int The unique ID of

a destination record

GetDestinationPrefixInfoRequest structure


i_dest int The unique ID of a destinationrecord

GetDestinationPrefixInfoResponse structure


destination_info DestinationPrefixInfo

structure

Complete information

about the destination; formore information, seebelow

DestinationPrefixInfo structure


i_dest int The unique ID ofthe destination record

destination string, max16 chars

Destination number

country string Country namesubdivision string Country subdivisiondescription string Text description for this entrydest_type string Destination typeiso_3166_1_a2 string A two-letter country code

defined in ISO 3166-1 alpha-2iso_3166_1_a3 string A three-letter country code

defined in ISO 3166-1alpha-3


49/391



i_country_subdivision int Refers to the ID of province orstate where the company isregistered

GetDestinationPrefixListRequest structure

Property Type Descriptionoffset int Number of rows to skip at the

beginning of the listlimit int Number of rows to retrievedestination string, max. 16

charsRefers to the pattern of thedestination prefix

order_by_destination string Specifies whether to sortdestinations:1 descending order0 ascending

If this field is empty thendestinations will be sorted bythe i_dest field

get_total int Get total number of theretrieved destination prefixes

GetDestinationPrefixListResponse structure


destination_list Array ofDestinationPrefixInfostructures

Set of destination datarecords

total int Total number of theretrieved destination datarecords

MatchDestinationGroupsRequest structure


i_tariff int The unique ID of the special tariffcontaining destination groups

number string A caller number for searching theappropriate destination group in

the tariffget_prefixes_list int, 0/1

(default 0)This indicates whether the listof destinations included in thisgroup will be retrieved: 0 retrieve, 1 do not retrieve


50/391



MatchDestinationGroupsResponse structure


dest_group_list Array ofDestinationGroupInfostructures

Set of destination groupdata records

DestinationGroupInfo structure


name string The destination group namedescription n string The destination group descriptioni_dest_group int The unique ID of the destination groupi_dest_group_set int The unique ID of the destination group

set to which the current destinationgroup belongs

prefixes string Comma separated list of destinations

included in the current destinationgroupused int Shows whether the destination group

set is used

GetDestGroupSetListRequest structure


name stringSearch pattern in the names ofdestination group sets


offset int

Number of rows to skip at the

beginning of the list

get_total intGet total number of the retrieveddestination group sets

GetDestGroupSetListResponse structure


dest_group_set_listArray ofDestGroupSetInfostructures

Set of destination group setdata records

total int

Total number of the

retrieved destination groupsets

AddUpdateDestGroupSetRequest structure



51/391



dest_group_set_infoArray ofDestGroupSetInfostructure

Complete informationabout the destination groupset; for more information,see below

AddUpdateDestGroupSetResponse structure


i_dest_group_set int The unique ID ofthe destination group set

DestGroupSetInfo srtucture



name string The destination groupset name

used int Shows whether thedestination group set is used

DeleteDestGroupSetRequest structure



DeleteDestGroupSetResponse structure

Property Type Descriptionsuccess int 1 in case of success, 0 incase of failure

DestGroupSetInfo structure


i_dest_group_set ** intThe unique ID of a destination groupset record

name string The destination group set name

used ** intShows whether the destination groupset is used

GetDestGroupListRequest structure


i_dest_group_set intThe unique ID of a destination group setrecord

name stringSearch pattern in the names of destinationgroups


52/391



prefix string

Prefix by which to search destinationgroups. Note that if you provide both nameand prefix properties, then search willbe done only by name


offset intNumber of rows to skip at the beginning ofthe list

get_total intGet total number of the retrieveddestination groups

GetDestGroupListResponse structure


dest_group_listArray ofDestinationGroupInfostructures

Set of destination groupdata records

total intTotal number of the

retrieved destination groups

AddDestGroupRequest structure



name string The destination groupname

add_destinations Array of IntList of destinations to beadded to the destinationgroup

AddDestGroupResponse structure


i_dest_group int The unique ID ofthe destination group

DeleteDestGroupRequest structure


i_dest_group int The unique ID of

the destination group

DeleteDestGroupResponse structure


success int 1 in case of success, 0 incase of failure


53/391



UpdateDestGroupRequest structure



name string The destination group

nameadd_destinations Array of Int List of destinations to be

added to the destinationgroup

delete_destinations Array of Int List of destinations to beremoved from thedestination group

UpdateDestGroupResponse structure



GetDestGroupInfoRequest structure


i_dest_group intThe unique ID of the destinationgroup record

prefix string

The prefix by which to searchdestinations. Note that the searchparametersprefix, countryand descriptionare exclusive with the following

priority:prefix->country->description. E.g.,if you provide both prefixand country properties, then searchwill be done only by the prefix

country string The country to search destinations

description stringDestination description to searchdestinations


offset intNumber of rows to skip at thebeginning of the list

get_total int Get the total number of the retrieveddestinations

GetDestGroupInfoResponse structure


name stringThe destination groupname


54/391



destination_list Array ofDestinationPrefixInfostructures

Set of destination datarecords

total intThe total number of theretrieved destinations

Access to Tariff Information

SOAP URI (namespace): https://portabilling-web.yourdomain.com/Porta/SOAP/Tariff

Tariff Information

get_tariff_info

Parameters: GetTariffInfoRequest

Return value: GetTariffInfoResponseRealm: administrator, reseller

This method allows an API user to get information about a tariff.

get_tariff_list

Parameters: GetTariffListRequestReturn value: GetTariffListResponseRealm: administrator, reseller

This method allows an API user to retrieve the list of tariffs.

add_tariff

Parameters:AddTariffRequest Return value:AddTariffResponseRealm: administrator

This method allows an API user to add a tariff.

update_tariff

Parameters: UpdateTariffRequest

Return value: UpdateTariffResponseRealm: administrator

This method allows an API user to update an existing tariff.

delete_tariff

Parameters: DeleteTariffRequest


55/391



Return value: DeleteTariffResponseRealm: administrator

This method allows an API user to delete an existing tariff.

Type Reference for Tariff Information

GetTariffInfoRequest structure


i_tariff int The unique ID of the tariffrecord

GetTariffInfoResponse structure


tariff_info TariffInfo structure Complete information

about the tariff; for moreinformation, see below

TariffInfo structure


i_tariff int ID of the tariff recordname string Tariff nameperiod string Discontinued.i_offpeak int Refers to ID of the off_peak

period recordcurrency string Tariff currencyfree_sec int Number of free seconds

granted for each callconnect_fee float Amount to be charged for

each successful calllogin_fee float Amount to be charged

immediately after the first userauthentication

description string Tariff descriptionpost_call_surcharge float Increases the total call cost by

the given valuei_tariff_template_upload int Refers to ID of the upload

templatei_tariff_template_download int Refers to ID of download

templatei_customer int ID of Customer Record

(managed by)short_description string Short tariff description


56/391



routing_ext string Flag that informs if the tariffcontains information aboutthe carriers routingpreferences

volume_based string Flag that informs if the tariffis volume based

i_dest_group_set int Refers to ID of destinationgroups

rounding int Quantity of digits after pointfor rounding

formula string Call rating formula thatapplies to new rates

rating_mode string Rating modei_service int Refers to ID of the service

type for which this tariff willbe used

type string Designates whom this tariff isapplied to.One of the following:

Customer

Vendor

Resellerhidden string Hidden flagusage_update string Usage update.

One of the following:

Always

Billable

GetTariffListRequest structure



limit int Number of rows to retrievesearch string Search pattern in the name

and description of the tariffi_customer int The unique ID of the customer

record (managed by)i_service int The unique ID of the service

recordapplied_to string One of the following:

Customer

Vendor

Reseller


57/391



GetTariffListResponse structure


tariff_list Array ofTariffInfostructures

Set of tariff data records

AddTariffRequest structure


tariff_info TariffInfo structure Complete informationabout the tariff; formore information, seebelow

AddTariffResponse structure


i_tariff int The unique ID of

the tariff record

UpdateTariffRequest structure


tariff_info TariffInfo structure Complete informationabout the tariff; for moreinformation, see below

UpdateTariffResponse structure


i_tariff int The unique ID ofthe tariff record

DeleteTariffRequest structure


i_tariff int The unique ID ofthe tariff record

DeleteTariffResponse structure


success int 1 in case of success, 0 incase of failure

Tariff Information (Override Tariff)

get_override_tariff

Parameters: GetOverrideTariffRequest


58/391



Return value: GetOverrideTariffResponseRealm: administrator, reseller

This method allows an API user to retrieve the override tariff.

get_override_tariff_list

Parameters: GetOverrideTariffListRequestReturn value: GetOverrideTariffListResponseRealm: administrator, reseller

This method allows an API user to retrieve the list of override tariffs for acustomer.

add_override_tariff

Parameters:AddUpdateOverrideTariffRequestReturn value:AddUpdateOverrideTariffResponse

Realm: administrator, reseller

This method allows an API user to add an override tariff rule.

update_override_tariff

Parameters:AddUpdateOverrideTariffRequestReturn value:AddUpdateOverrideTariffResponseRealm: administrator, reseller

PortaSwitch Interfaces MR47

Documents

Transcript of PortaSwitch Interfaces MR47