lib/Net/Vitelity.pm

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