lib/Net/Ikano.pm

   1 package Net::Ikano;
   2
   3 use warnings;
   4 use strict;
   5 use Net::Ikano::XMLUtil;
   6 use LWP::UserAgent;
   7 use Data::Dumper;
   8
   9 =head1 NAME
  10
  11 Net::Ikano - Interface to Ikano wholesale DSL API
  12
  13 =head1 VERSION
  14
  15 Version 0.01
  16
  17 =cut
  18
  19 our $VERSION = '0.01';
  20
  21 our $URL = 'https://orders.value.net/OsirisWebService/XmlApi.aspx';
  22
  23 our $SCHEMA_ROOT = 'https://orders.value.net/osiriswebservice/schema/v1';
  24
  25 our $API_VERSION = "1.0";
  26
  27 our @orderType = qw( NEW CANCEL CHANGE );
  28
  29 our @orderStatus = qw( NEW PENDING CANCELLED COMPLETED ERROR );
  30
  31 our $AUTOLOAD;
  32
  33 =head1 SYNOPSIS
  34
  35     use Net::Ikano;
  36
  37     my $ikano = Net::Ikano->new(
  38                'keyid' => $your_ikano_api_keyid,
  39                'password'  => $your_ikano_admin_user_password,
  40                'debug' => 1 # remove this for prod
  41                'reqpreviewonly' => 1 # remove this for prod
  42                'minimalQualResp' => 1 # on quals, return pairs of ProductCustomId+TermsId only
  43                'minimalOrderResp' => 1 # return minimal data on order responses
  44                              );
  45
  46 =head1 SUPPORTED API METHODS
  47
  48 =item ORDER
  49
  50 NOTE: supports orders by ProductCustomId only
  51
  52 $ikano->ORDER(
  53     {
  54         orderType => 'NEW',
  55         ProductCustomId => 'abc123',
  56         TermsId => '123',
  57         DSLPhoneNumber => '4167800000',
  58         Password => 'abc123',
  59         PrequalId => '12345',
  60         CompanyName => 'abc co',
  61         FirstName => 'first',
  62         LastName => 'last',
  63         MiddleName => '',
  64         ContactMethod => 'PHONE',
  65         ContactPhoneNumber => '4167800000',
  66         ContactEmail => 'x@x.ca',
  67         ContactFax => '',
  68         DateToOrder => '2010-11-29',
  69         RequestClientIP => '127.0.0.1',
  70         IspChange => 'NO',
  71         IspPrevious => '',
  72         CurrentProvider => '',
  73     }
  74 );
  75
  76
  77 =item CANCEL
  78
  79 $i->CANCEL(
  80     { OrderId => 555 }
  81 );
  82
  83
  84 =item PREQUAL
  85
  86 $ikano->PREQUAL( {
  87     AddressLine1 => '123 Test Rd',
  88     AddressUnitType => '',
  89     AddressUnitValue =>  '',
  90     AddressCity =>  'Toronto',
  91     AddressState => 'ON',
  92     ZipCode => 'M6C 2J9', # or 12345
  93     Country => 'CA', # or US
  94     LocationType => 'R', # or B
  95     PhoneNumber => '4167800000',
  96     RequestClientIP => '127.0.0.1',
  97     CheckNetworks => 'ATT,BELLCA,VER', # either one or command-separated like this
  98 } );
  99
 100
 101 =item ORDERSTATUS
 102
 103 $ikano->ORDERSTATUS(
 104     { OrderId => 1234 }
 105 );
 106
 107
 108 =item PASSWORDCHANGE
 109
 110 $ikano->PASSWORDCHANGE( {
 111             DSLPhoneNumber => '4167800000',
 112             NewPassword => 'xxx',
 113         } );
 114
 115
 116 =item CUSTOMERLOOKUP
 117
 118 $ikano->CUSTOMERLOOKUP( { PhoneNumber => '4167800000' } );
 119
 120
 121 =item ACCOUNTSTATUSCHANGE
 122
 123 $ikano->ACCOUNTSTATUSCHANGE(( {
 124             type => 'SUSPEND',
 125             DSLPhoneNumber => '4167800000',
 126             DSLServiecId => 123,
 127         } );
 128
 129 =cut
 130
 131 sub new {
 132     my ($class,%data) = @_;
 133     die "missing keyid and/or password"
 134         unless defined $data{'keyid'} && defined $data{'password'};
 135     my $self = {
 136         'keyid' => $data{'keyid'},
 137         'password' => $data{'password'},
 138         'username' => $data{'username'} ? $data{'username'} : 'admin',
 139         'debug' => $data{'debug'} ? $data{'debug'} : 0,
 140         'reqpreviewonly' => $data{'reqpreviewonly'} ? $data{'reqpreviewonly'} : 0,
 141         };
 142     bless $self, $class;
 143     return $self;
 144 }
 145
 146
 147 sub req_ORDER {
 148    my ($self, $args) = (shift, shift);
 149
 150     return "invalid order data" unless defined $args->{orderType}
 151         && defined $args->{ProductCustomId} && defined $args->{DSLPhoneNumber};
 152    return "invalid order type ".$args->{orderType}
 153     unless grep($_ eq $args->{orderType}, @orderType);
 154
 155     # XXX: rewrite this uglyness?
 156     my @ignoreFields = qw( orderType ProductCustomId );
 157     my %orderArgs = ();
 158     while ( my ($k,$v) = each(%$args) ) {
 159         $orderArgs{$k} = [ $v ] unless grep($_ eq $k,@ignoreFields);
 160     }
 161
 162     return Order => {
 163         type => $args->{orderType},
 164         %orderArgs,
 165         ProductCustomId => [ split(',',$args->{ProductCustomId}) ],
 166     };
 167 }
 168
 169 sub resp_ORDER {
 170    my ($self, $resphash, $reqhash) = (shift, shift);
 171    return "invalid order response" unless defined $resphash->{OrderResponse};
 172    return $resphash->{OrderResponse};
 173 }
 174
 175 sub req_CANCEL {
 176    my ($self, $args) = (shift, shift);
 177
 178     return "no order id for cancel" unless defined $args->{OrderId};
 179
 180     return Cancel => {
 181         OrderId => [ $args->{OrderId} ],
 182     };
 183 }
 184
 185 sub resp_CANCEL {
 186    my ($self, $resphash, $reqhash) = (shift, shift);
 187    return "invalid cancel response" unless defined $resphash->{OrderResponse};
 188    return $resphash->{OrderResponse};
 189 }
 190
 191 sub req_ORDERSTATUS {
 192    my ($self, $args) = (shift, shift);
 193
 194    return "ORDERSTATUS is supported by OrderId only"
 195     if defined $args->{PhoneNumber} || !defined $args->{OrderId};
 196
 197     return OrderStatus => {
 198         OrderId => [ $args->{OrderId} ],
 199     };
 200 }
 201
 202 sub resp_ORDERSTATUS {
 203    my ($self, $resphash, $reqhash) = (shift, shift);
 204    return "invalid order response" unless defined $resphash->{OrderResponse};
 205    return $resphash->{OrderResponse};
 206 }
 207
 208 sub req_ACCOUNTSTATUSCHANGE {
 209    my ($self, $args) = (shift, shift);
 210    return "invalid account status change request" unless defined $args->{type}
 211     && defined $args->{DSLServiceId} && defined $args->{DSLPhoneNumber};
 212
 213    return AccountStatusChange => {
 214        type => $args->{type},
 215         DSLPhoneNumber => [ $args->{DSLPhoneNumber} ],
 216         DSLServiceId => [ $args->{DSLServiceId} ],
 217     };
 218 }
 219
 220 sub resp_ACCOUNTSTATUSCHANGE {
 221    my ($self, $resphash, $reqhash) = (shift, shift);
 222     return "invalid account status change response"
 223         unless defined $resphash->{AccountStatusChangeResponse}
 224         && defined $resphash->{AccountStatusChangeResponse}->{Customer};
 225     return $resphash->{AccountStatusChangeResponse}->{Customer};
 226 }
 227
 228 sub req_CUSTOMERLOOKUP {
 229    my ($self, $args) = (shift, shift);
 230    return "invalid customer lookup request" unless defined $args->{PhoneNumber};
 231    return CustomerLookup => {
 232         PhoneNumber => [ $args->{PhoneNumber} ],
 233    };
 234 }
 235
 236 sub resp_CUSTOMERLOOKUP {
 237    my ($self, $resphash, $reqhash) = (shift, shift);
 238    return "invalid customer lookup response"
 239     unless defined $resphash->{CustomerLookupResponse}
 240         && defined $resphash->{CustomerLookupResponse}->{Customer};
 241    return $resphash->{CustomerLookupResponse}->{Customer};
 242 }
 243
 244 sub req_PASSWORDCHANGE {
 245    my ($self, $args) = (shift, shift);
 246    return "invalid arguments to PASSWORDCHANGE"
 247         unless defined $args->{DSLPhoneNumber} && defined $args->{NewPassword};
 248
 249    return PasswordChange => {
 250         DSLPhoneNumber => [ $args->{DSLPhoneNumber} ],
 251         NewPassword => [ $args->{NewPassword} ],
 252    };
 253 }
 254
 255 sub resp_PASSWORDCHANGE {
 256    my ($self, $resphash, $reqhash) = (shift, shift);
 257    return "invalid change password response"
 258         unless defined $resphash->{ChangePasswordResponse};
 259    return $resphash->{ChangePasswordResponse};
 260 }
 261
 262 sub req_PREQUAL {
 263    my ($self, $args) = (shift, shift);
 264    return PreQual => {
 265         Address =>  [ { (
 266             map { $_ => [ $args->{$_} ]  }
 267                 qw( AddressLine1 AddressUnitType AddressUnitValue AddressCity
 268                     AddressState ZipCode LocationType Country )
 269             )  } ],
 270         ( map { $_ => [ $args->{$_} ] } qw( PhoneNumber RequestClientIP ) ),
 271         CheckNetworks => [ {
 272             Network => [ split(',',$args->{CheckNetworks}) ]
 273         } ],
 274        };
 275 }
 276
 277 sub resp_PREQUAL {
 278     my ($self, $resphash, $reqhash) = (shift, shift);
 279     return "invalid prequal response" unless defined $resphash->{PreQualResponse};
 280     return $resphash->{PreQualResponse};
 281 }
 282
 283 sub AUTOLOAD {
 284     my $self = shift;
 285
 286     $AUTOLOAD =~ /(^|::)(\w+)$/ or die "invalid AUTOLOAD: $AUTOLOAD";
 287     my $cmd = $2;
 288     return if $cmd eq 'DESTROY';
 289
 290     my $reqsub = "req_$cmd";
 291     my $respsub = "resp_$cmd";
 292     die "invalid request type $cmd"
 293         unless defined &$reqsub && defined &$respsub;
 294
 295     my $reqargs = shift;
 296
 297     my $xs = new Net::Ikano::XMLUtil(RootName => undef, SuppressEmpty => 1 );
 298     my $reqhash = {
 299             OsirisRequest   => {
 300                 type    => $cmd,
 301                 keyid   => $self->{keyid},
 302                 username => $self->{username},
 303                 password => $self->{password},
 304                 version => $API_VERSION,
 305                 xmlns   => "$SCHEMA_ROOT/osirisrequest.xsd",
 306                 $self->$reqsub($reqargs),
 307             }
 308         };
 309
 310
 311     my $reqxml = "<?xml version=\"1.0\"?>\n".$xs->XMLout($reqhash, NoSort => 1);
 312
 313     # XXX: validate against their schema to ensure we're not sending invalid XML?
 314
 315     warn "DEBUG REQUEST\n\tHASH:\n ".Dumper($reqhash)."\n\tXML:\n $reqxml \n\n"
 316         if $self->{debug};
 317
 318     my $ua = LWP::UserAgent->new;
 319
 320     return "posting disabled for testing" if $self->{reqpreviewonly};
 321
 322     my $resp = $ua->post($URL, Content_Type => 'text/xml', Content => $reqxml);
 323     return "invalid HTTP response from Ikano: " . $resp->status_line
 324         unless $resp->is_success;
 325     my $respxml = $resp->decoded_content;
 326
 327     $xs = new Net::Ikano::XMLUtil(RootName => undef, SuppressEmpty => '',
 328         ForceArray => [ 'Address', 'Product', 'StaticIp', 'OrderNotes' ] );
 329     my $resphash = $xs->XMLin($respxml);
 330
 331     warn "DEBUG RESPONSE\n\tHASH:\n ".Dumper($resphash)."\n\tXML:\n $respxml"
 332         if $self->{debug};
 333
 334     # XXX: validate against their schema to ensure they didn't send us invalid XML?
 335
 336     return "invalid response received from Ikano"
 337         unless defined $resphash->{responseid} && defined $resphash->{version}
 338             && defined $resphash->{type};
 339
 340     return "FAILURE response received from Ikano: "
 341         . $resphash->{FailureResponse}->{FailureMessage}
 342         if $resphash->{type} eq 'FAILURE';
 343
 344     my $validRespTypes = {
 345         'PREQUAL' => qw( PREQUAL ),
 346         'ORDERSTATUS' => qw( ORDERSTATUS ),
 347         'ORDER' => qw( NEWORDER CHANGEORDER CANCELORDER ),
 348         'CANCEL' => qw( ORDERCANCEL ),
 349         'PASSWORDCHANGE' => qw( PASSWORDCHANGE ),
 350         'ACCOUNTSTATUSCHANGE' => qw( ACCOUNTSTATUSCHANGE ),
 351         'CUSTOMERLOOKUP' => qw( CUSTOMERLOOKUP ),
 352     };
 353
 354     return "invalid response type ".$resphash->{type}." for request type $cmd"
 355         unless grep( $_ eq $resphash->{type}, $validRespTypes->{$cmd});
 356
 357     return $self->$respsub($resphash,$reqhash);
 358 }
 359
 360
 361 =head1 AUTHOR
 362
 363 Erik Levinson, C<< <levinse at freeside.biz> >>
 364
 365 =head1 BUGS
 366
 367 Please report any bugs or feature requests to C<bug-net-ikano at rt.cpan.org>, or through
 368 the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Ikano>.  I will be notified, and then you'll
 369 automatically be notified of progress on your bug as I make changes.
 370
 371 =head1 SUPPORT
 372
 373 You can find documentation for this module with the perldoc command.
 374
 375     perldoc Net::Ikano
 376
 377 You can also look for information at:
 378
 379 =over 4
 380
 381 =item * RT: CPAN's request tracker
 382
 383 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Ikano>
 384
 385 =item * AnnoCPAN: Annotated CPAN documentation
 386
 387 L<http://annocpan.org/dist/Net-Ikano>
 388
 389 =item * CPAN Ratings
 390
 391 L<http://cpanratings.perl.org/d/Net-Ikano>
 392
 393 =item * Search CPAN
 394
 395 L<http://search.cpan.org/dist/Net-Ikano>
 396
 397 =back
 398
 399 =head1 ACKNOWLEDGEMENTS
 400
 401 This module was developed by Freeside Internet Services, Inc.
 402 If you need a complete, open-source web-based application to manage your
 403 customers, billing and trouble ticketing, please visit http://freeside.biz/
 404
 405 =head1 COPYRIGHT & LICENSE
 406
 407 Copyright 2010 Freeside Internet Services, Inc.
 408 All rights reserved.
 409
 410 This program is free software; you can redistribute it and/or modify it
 411 under the same terms as Perl itself.
 412
 413 =cut
 414
 415 1;
 416