Sandbox Web Control Panel

Perl SOAP::Lite

Method list
  Before starting
  1. Get countries
  2. Get cities
  3. Order DID
  4. Build mapping for new DID
  5. Change mapping for DID
  6. Get region details
  7. Get DID details
  8. Order autorenew status
  10. Cancel DID
  11. Cancel Order

Error codes:
* 100 Access denied
* 105 Order already exists
* 106 DID ID: DID_ID NOT found
* 107 Invalid Protocol
* 108 DID: DIDNUMBER NOT found
* 109 DID: DIDNUMBER in Pending/Remove status
* 110 DID: DIDNUMBER NOT renewed
* 111 Invalid status code. Valid codes: 0 - Disable, 1 - Enable
* 113 Order NOT found for DIDNUMBER
* 114 Order already canceled for DIDNUMBER
* 115 ORDER: Cannot cancel not pending order for DIDNUMBER. Please, use did_cancel
* 120 UNIQ: UNIQUEKEY NOT found
* 121 No cities for this country
* 150 Sandbox error. DIDs max limit reached
* 200 Internal Server Error

Before starting

a. SOAP::Lite
In order to use our Web Service, you need to download Perl SOAP:Lite module.
The sources can be downloaded from http://www.soaplite.com/.

b. Authentication Key
You will receive from DID World Wide the authentication key.
Below there are sample codes, how to build authentication string, to pass to methods:
1. This sample is used on reseller's production server for public.
Web Site WSDL URL: http://api.didww.com/api/?wsdl

#!/usr/bin/perl -w

use Digest::SHA1 qw(sha1_hex);

$username = 'username@domain.com';
$key = '12345678909';

my $auth_string = sha1_hex($username.$key);

2. This sample is used on DID World Wide Sandbox for testing.
Please, note: We are adding word "sandbox" to authentication string
Web Site WSDL URL: http://sandbox.didww.com/api/?wsdl

#!/usr/bin/perl -w

use Digest::SHA1 qw(sha1_hex);

$username = 'username@domain.com';
$key = '12345678909';

my $auth_string = sha1_hex($username.$key.'sandbox');

1. Get countries list

This method will return the list of countries from active coverage list.

Method Signature

sub getcountries($auth_string);

string $auth_string

Return array: $result

country_name: United States
country_id: 324
country_prefix: 1
...

Code example

#!/usr/bin/perl -w

use Digest::SHA1 qw(sha1_hex);

$username = 'username@domain.com';
$key = '12345678909';

my $auth_string = sha1_hex($username.$key.'sandbox');

use SOAP::Lite;

my $result = SOAP::Lite
 -> uri('http://sandbox.didww.com/api/didww')
 -> proxy ('http://sandbox.didww.com/api')
 -> getcountries($auth_string);


if ($result->fault)
{
  print $result->faultcode, " ", $result->faultstring, "\n";
}
else
{
  my @list = @{$result->result};
  foreach my $list(@list) 
  {
    foreach my $key (keys %{$list})
    {
      print $key, ": ", $list->{$key} || '', "\n";
    }
  }
}

2. Get cities list

This method will return the list of available cities by country ID along with reseller's monthly price.
The country ID value is passed from method getcountries
You will need to assign requested 'country_id' from array list to $country_id variable.

Method Signature

sub getcities($auth_string, $country_id);

string $auth_string

integer $country_id

Return array: $result

monthly: 8.50
city_prefix: 202
city_name: Washington  DC
uniq: 134123543
...

Code example

#!/usr/bin/perl -w

use Digest::SHA1 qw(sha1_hex);

$username = 'username@domain.com';
$key = '12345678909';

my $auth_string = sha1_hex($username.$key.'sandbox');

$country_id = 225;

use SOAP::Lite;

my $result = SOAP::Lite
 -> uri('http://sandbox.didww.com/api/didww')
 -> proxy ('http://sandbox.didww.com/api')
 -> getcities($auth_string, $country_id);


if ($result->fault)
{
	print $result->faultcode, " ", $result->faultstring, "\n";
}
else
{
	my @list = @{$result->result};
	foreach my $list(@list) 
	{
		foreach my $key (keys %{$list})
		{
			print $key, ": ", $list->{$key} || '', "\n";
		}
		print "\n";
	}
}

3. Order DID

This method will make a new order.
The $hashkey value must be different for every new order. If you pass the same hash key again, the Web Service will throw exception.
The 'uniq' variable from method getcities should be assigned to $uniq variable, in order to find DID by this unique key.
This method will return two values, DID ID and DID Number.

Method Signature

sub neworder($auth_string, $hashkey, $uniq, $autorenew, $period);

string $auth_string

string $hashkey

string $uniq

integer $autorenew

integer $period

Return array: $result

did_number: 12021234485
did_id: 32

Code example

#!/usr/bin/perl -w

use Digest::SHA1 qw(sha1_hex);

$username = 'username@domain.com';
$key = '12345678909';

my $auth_string = sha1_hex($username.$key.'sandbox');

$hashkey = sha1_hex('31JFGJHGJHFGJ35246JHFGJHF');
$uniq = 225128202;
$period = 3;

use SOAP::Lite;

my $result = SOAP::Lite
 -> uri('http://sandbox.didww.com/api/didww')
 -> proxy ('http://sandbox.didww.com/api')
 -> neworder($auth_string, $hashkey, $uniq $autorenew $period);


if ($result->fault)
{
  print $result->faultcode, " ", $result->faultstring, "\n";
}
else
{
	my $data = $result->result;
	my @aval  = keys %$data;
	foreach my $val (@aval)
	{
		print $val, ": ", $data->{$val}, "\n";
	}
}

4. Build mapping for DID

This method will build mapping for selected DID ID. The DID ID value is passed from method neworder.
You will need to assign 'did_id' from array list to $did_id variable.
Note: If you want to use the Default mapping, this method should be ignored.

Map Protocols are:
1 - SIP
2 - IAX2
3 - H.323

The default format of URI mapping is PROTOCOL/IPADDRESS.
If you want add DIDNUMBER to URI, please use $add_did = 1. The format will be: PROTOCOL/IPADDRESS/DIDNUMBER

Method Signature

sub buildmapping($auth_string, $did_id, $map_proto, $map_uri, $add_did);

string $auth_string

integer $did_id

integer $map_proto

string $map_uri

integer $add_did

Return: value (0 - Success)

Return: 0

Code example

#!/usr/bin/perl -w

use Digest::SHA1 qw(sha1_hex);

$username = 'username@domain.com';
$key = '12345678909';

my $auth_string = sha1_hex($username.$key.'sandbox');

$did_id = 37;
$map_proto = 2; # 1 - SIP, 2 - IAX2, 3 - H.323
$map_uri = '444:444@domain.com';
$add_did = 0;

use SOAP::Lite;

my $result = SOAP::Lite
 -> uri('http://sandbox.didww.com/api/didww')
 -> proxy ('http://sandbox.didww.com/api')
 -> buildmapping($auth_string, $did_id, $map_proto, $map_uri, $add_did);


if ($result->fault)
{
  print $result->faultcode, " ", $result->faultstring, "\n";
}
else
{
  print "Return: ",  $result->result, "\n";
}

5. Change mapping for DID

This method will change mapping for selected DID number.

Map Protocols are:
1 - SIP
2 - IAX2
3 - H.323

The default format of URI mapping is PROTOCOL/IPADDRESS.
If you want add DIDNUMBER to URI, please use $add_did = 1. The format will be: PROTOCOL/IPADDRESS/DIDNUMBER

Method Signature

sub change_mapping($auth_string, $did_number, $map_proto, $map_uri,
							 $add_did);

string $auth_string

string $did_number

integer $map_proto

string $map_uri

integer $add_did

Return: value (0 - Success)

Return: 0

Code example

#!/usr/bin/perl -w

use Digest::SHA1 qw(sha1_hex);

$username = 'username@domain.com';
$key = '12345678909';

my $auth_string = sha1_hex($username.$key.'sandbox');

$did_number = '1516700100';
$map_proto = 2; # 1 - SIP, 2 - IAX2, 3 - H.323
$map_uri = '444:444@domain.com';
$add_did = 0;

use SOAP::Lite;

my $result = SOAP::Lite
 -> uri('http://sandbox.didww.com/api/didww')
 -> proxy ('http://sandbox.didww.com/api')
 -> change_mapping($auth_string, $did_number, $map_proto, $map_uri,
							 $add_did);


if ($result->fault)
{
  print $result->faultcode, " ", $result->faultstring, "\n";
}
else
{
  print "Return: ",  $result->result, "\n";
}

6. Get region details

This method will return region details

Method Signature

sub get_did_details($auth_string, $uniq);

string $auth_string

string $uniq

Return array: $result

country_name: United States
city_name: Washington  DC
monthly: 8.50

7. Get DID details

This method will return DID details

Method Signature

sub get_did_details($auth_string, $did_number);

string $auth_string

string $did_number

Return array: $result

did_country_name: United States
did_city_name: New York NY
did_number_format: 1-516-700100
did_status: Active
did_timeleft: 1 mon
did_expire_date: 2007-06-23 03:06:27
did_order_id: 123456
did_order_status: Completed
did_autorenew: Disabled
did_mapping_format: SIP/212.150.36.116/1516700100
did_mapping_default: No
did_id: 205
did_price: 5.00

8. Order autorenew status

This method will change Auto-renew status.
0 - Disable Auto-renew
1 - Enable Auto-Renew

Method Signature

sub order_autorenew_status($auth_string, $did_number, $autorenew);

string $auth_string

string $did_number

integer $autorenew

Return: value (0 - Success)

Return: 0

9. Renew DID

This method will renew DID for provided period (months).
Valid periods are: 1, 3, 6, 12, 24 Months
Autorenew: 0 - Disable, 1 - Enable

Method Signature

sub new_order_renew($auth_string, $did_number, $period, $autorenew);

string $auth_string

string $did_number

integer $period

integer $autorenew

Return array: $result

did_country_name: United States
did_city_name: New York NY
did_number_format: 1-516-700100
did_status: Active
did_timeleft: 2 mon
did_expire_date: 2007-07-23 03:06:27
did_order_id: 123457
did_order_status: Pending
did_autorenew: Disabled
did_mapping_format: SIP/212.150.36.116/1516700100
did_mapping_default: No
did_id: 205

10. Cancel DID

This method will cancel DID.
Note: Canceled DIDs cannot be restored.

Method Signature

sub did_cancel($auth_string, $did_number);

string $auth_string

string $did_number

Return: value (0 - Success)

Return: 0

11. Cancel Order

This method will cancel any Pending Order.
Note: Canceled Orders cannot be restored. Sandbox does not support this function.

Method Signature

sub order_cancel($auth_string, $did_number);

string $auth_string

string $did_number

Return: value (0 - Success)

Return: 0