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