lib/Net/Vitelity.pm

   1 package Net::Vitelity;
   2
   3 use warnings;
   4 use strict;
   5 use LWP::UserAgent;
   6
   7 =head1 NAME
   8
   9 Net::Vitelity - Interface to Vitelity API
  10
  11 =cut
  12
  13 our $VERSION = '0.04';
  14
  15 our $AUTOLOAD;
  16
  17 =head1 SYNOPSIS
  18
  19     use Net::Vitelity;
  20
  21     my $vitelity = Net::Vitelity->new(
  22                                        'login'   => $your_login,
  23                                        'pass'    => $your_pass,
  24                                        'apitype' => 'api', #api, fax or lnp
  25                                        'debug'   => 0,
  26                                      );
  27
  28 =head1 METHODS
  29
  30 =cut
  31
  32 =head2 new
  33
  34 Create a new Net::Vitelity object.  login and pass are required.
  35
  36 =cut
  37
  38 sub new {
  39     my ($class,%data) = @_;
  40     die "missing user and/or password" unless defined $data{'login'} && defined $data{'pass'};
  41     my $self = { 'login' => $data{'login'}, 'pass' => $data{'pass'} };
  42     $self->{apitype} = $data{'apitype'} ? $data{'apitype'} : 'api';
  43     $self->{debug} = $data{'debug'} ? 1 : 0;
  44     bless $self, $class;
  45     return $self;
  46 }
  47
  48 sub AUTOLOAD {
  49   my $self = shift;
  50
  51   $AUTOLOAD =~ /(^|::)(\w+)$/ or die "unparsable AUTOLOAD: $AUTOLOAD";
  52   my $cmd = $2;
  53   return if $cmd eq 'DESTROY';
  54
  55   my $ua = LWP::UserAgent->new;
  56
  57   #XXX md5 encrypt pass
  58
  59   my $URL_API = 'http://api.vitelity.net/api.php';
  60   my $URL_FAX = 'http://api.vitelity.net/fax.php';
  61   my $URL_LNP = 'http://api.vitelity.net/lnp.php';
  62
  63   my $url = $URL_API;
  64   $url = $URL_FAX if $self->{apitype} eq 'fax';
  65   $url = $URL_LNP if $self->{apitype} eq 'lnp';
  66
  67   if ( $self->{debug} ) {
  68     warn "Vitelity $cmd ($url)\n";
  69     my %hash = @_;
  70     warn "  $_: $hash{$_}\n" foreach keys %hash;
  71   }
  72
  73   my $response = $ua->post($url, {
  74                     login => $self->{login},
  75                     pass  => $self->{pass},
  76                     cmd   => $cmd,
  77                     @_,
  78                   }
  79            );
  80
  81   die $response->status_line unless $response->is_success;
  82
  83   my $content = $response->decoded_content;
  84
  85   $content =~ /x\[\[(.*)\[\[x/s;
  86   $content = $1;
  87
  88   wantarray ? split("\n", $content) : $content;
  89
  90 }
  91
  92 =head2 listtollfree
  93
  94 List ALL available toll free numbers
  95
  96 Possible Results: none OR [list of tf numbers]
  97
  98 =head2 callfromclick
  99
 100 Sends someone a phone call that then connects them to customer service/another number.
 101
 102 Options: number=number AND servicenumber=number
 103
 104 Possible Results:OK or INVALID
 105
 106 =head2 listlocal
 107
 108 Lists ALL available local numbers in a specific state and ratecenter
 109
 110 Requires: state=STATE
 111
 112 Options: type=unlimited OR type=pri OR withrates=yes
 113                ratecenter=RATECENTER
 114
 115 Possible Results: unavailable or missing or [list of dids]
 116
 117 =head2 gettollfree
 118
 119 Orders a specific toll free number in our available list (SLOW)
 120 Requires: did=TOLL-FREE-NUMBER
 121 Options: routesip=route_to_this_subaccount
 122 Possible Results: success or unavailable or missingdid
 123
 124 =head2 getlocaldid
 125
 126 Orders a specific local number from our available list
 127
 128 Requires: did=AVAILABLE-LOCAL-NUMBER
 129
 130 Options: type=perminute OR type=unlimited OR type=your-pri OR
 131                routesip=route_to_this_subaccount
 132
 133 Possible Results: invalid or success or missingdid
 134
 135 =head2 removedid
 136
 137 Remove Local or Toll Free DID from account
 138
 139 Requires: did=AVAILABLE-LOCAL-NUMBER
 140
 141 Possible Results: success OR unavailable OR missingdid
 142
 143 =head2 listratecenters
 144
 145 Lists all of the available rate centers for a specific state line by line
 146
 147 Requires: state=STATE (ie, state=CO)
 148
 149 Options: type=perminute OR type=unlimited OR type=pri
 150
 151 Possible Results: unavailable OR missingdata OR [list of ratecenters]
 152
 153 =head2 listavailratecenters
 154
 155 Lists all available rate centers DIDs are currently in stock for a specific state line by line
 156
 157 Requires: state=STATE (ie, state=CO)
 158
 159 Options: type=unlimited OR type=pri
 160
 161 Possible Results: missingdata OR unavailable or [list of ratecenters]
 162
 163 =head2 requestvanity
 164
 165 Orders a specific available toll free number from the SMS database.
 166
 167 Requires: did=8009879891 (number can be any available number)
 168
 169 Possible Results: missingdata OR exists OR success
 170
 171 =head2 searchtoll
 172
 173 Searches the SMS/800 database for an available number matching the specific data you provide
 174
 175 Requires: did=8**333****
 176
 177 Possible Results: none OR missingdata OR [list of avail numbers]
 178
 179 =head2 listavailstates
 180
 181 Lists all states that have DIDs which are currently in stock
 182
 183 Options: type=perminute OR type=unlimited OR type=pri
 184
 185 Possible Results: unavailable OR [list of states]
 186
 187 =head2 liststates
 188
 189 Lists all available DID states line by line
 190
 191 Options: type=perminute OR type=unlimited OR type=pri
 192
 193 Possible Results: unavailable OR [list of states]
 194
 195 =head2 cnam
 196
 197 Lookup a specific caller id number for the name
 198
 199 Requires: did=3037855015 (number)
 200
 201 Possible Results: missingdata OR [cnam value]
 202
 203 =head2 searchtoll
 204
 205 Searches the SMS/800 database for an available number matching the specific data you provide
 206
 207 Requires: did=8**333****
 208
 209 Possible Results: none OR missingdata OR [list of avail numbers]
 210
 211 =head2 localbackorder
 212
 213 Orders a specific local number from our available list
 214
 215 Requires: ratecenter=RATECENTER and state=STATE
 216
 217 Options: type=perminute OR type=unlimited
 218
 219 Possible Results: invalid OR ok OR missing
 220
 221 =head2 reroute
 222
 223 Changes the sub account a DID rings to.
 224
 225 Requires: did=DID_NUMBER & routesip=SIP_SUB_ACCOUNT
 226
 227 Possible Results: missingdata OR ok OR invalid
 228
 229 =head2 balance
 230
 231 Reports back your current account balance
 232
 233 =head2 listdids
 234
 235 Lists all current Local and Toll free DIDs
 236
 237 Options: extra=yes
 238
 239 Results: number,ratecenter,price_per_minute,subaccount
 240
 241 extra=yes adds STATE,MONTHLY_DID_RATE
 242
 243 =head2 routeall
 244
 245 Changes the routing on all dids to a specific sip account
 246
 247 Requires: routesip=sub_account OR routesip=login (routes to main)
 248
 249 Possible Results: ok OR invalid
 250
 251 =head2 getrate
 252
 253 Gets a rate on a specific domestic or International call
 254
 255 Requires: number=[countrycode_thenumber] ex: 01144.. or 1303..
 256
 257 Results: invalid OR the_rate_per_minute
 258
 259 =head2 subaccounts
 260
 261 Lists sub accounts
 262
 263 Requires: do=list
 264
 265 Possible Results: subaccount list separated by return OR invalid
 266
 267 =head1 All Possible Result Return Codes
 268
 269 =over 4
 270
 271 =item success
 272
 273 The request you made was successful
 274
 275 =item missingdata
 276
 277 You are missing login= or pass= or cmd= or other in your URL string
 278
 279 =item invalidauth
 280
 281 You have submitted an invalid login or password
 282
 283 =item missingrc
 284
 285 You are missing the ratecenter or state for a specific local did order
 286
 287 =item unavailable
 288
 289 The number you requested is not available
 290
 291 =item none
 292
 293 There are no numbers available
 294
 295 =item missingdid
 296
 297 you are missing &did=number
 298
 299 =item list of data
 300
 301 If you asked for a list of numbers and we had some available, they will be listed.
 302
 303 In a list contect, all entries will be returned in a list.  In a scalar
 304 scalar context, entries will be separated by newlines.
 305
 306 =back
 307
 308 =head1 AUTHOR
 309
 310 Ivan Kohler, C<< <ivan-vitelity at freeside.biz> >>
 311
 312 =head1 BUGS
 313
 314 Please report any bugs or feature requests to C<bug-net-vitelity at rt.cpan.org>, or through
 315 the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Vitelity>.  I will be notified, and then you'll
 316 automatically be notified of progress on your bug as I make changes.
 317
 318 =head1 SUPPORT
 319
 320 You can find documentation for this module with the perldoc command.
 321
 322     perldoc Net::Vitelity
 323
 324 You can also look for information at:
 325
 326 =over 4
 327
 328 =item * RT: CPAN's request tracker
 329
 330 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Vitelity>
 331
 332 =item * AnnoCPAN: Annotated CPAN documentation
 333
 334 L<http://annocpan.org/dist/Net-Vitelity>
 335
 336 =item * CPAN Ratings
 337
 338 L<http://cpanratings.perl.org/d/Net-Vitelity>
 339
 340 =item * Search CPAN
 341
 342 L<http://search.cpan.org/dist/Net-Vitelity>
 343
 344 =back
 345
 346 =head1 ADVERTISEMENTS
 347
 348 This module was developed by Freeside Internet Services, Inc.
 349 Need a complete, open-source back-office and customer self-service solution?
 350 The Freeside software includes Vitelity integration, CDR rating,
 351 invoicing, credit card and electronic check processing, integrated trouble
 352 ticketing and customer signup and self-service web interfaces.
 353
 354 http://freeside.biz/
 355
 356 =head1 COPYRIGHT & LICENSE
 357
 358 Copyright 2009-2017 Freeside Internet Services, Inc.
 359 All rights reserved.
 360
 361 This program is free software; you can redistribute it and/or modify it
 362 under the same terms as Perl itself.
 363
 364 =cut
 365
 366 1;
 367