12 use vars qw($VERSION @ISA $DEBUG @login_opt); #$WARN );
13 # @EXPORT @EXPORT_OK %EXPORT_TAGS);
16 # This allows declaration use Net-Artera ':all';
17 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
19 #%EXPORT_TAGS = ( 'all' => [ qw(
23 #@EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
34 Net::Artera - Perl extension for Artera XML API.
40 my $connection = new Net::Artera (
41 'username' => 'reseller_username',
42 'password' => 'reseller_password',
48 This is a Perl module which speaks the Artera XML API.
49 See <http://www.arteraturbo.com>. Artera Resellers can use this module
50 to access some features of the API.
56 =item new [ OPTIONS_HASHREF | OPTION => VALUE ... ]
58 Constructor. Options can be passed as a hash reference or a list. Options are
61 Available options are:
65 =item username - Reseller username
67 =item password - Reseller password
69 =item rid - Reseller ID (RID)
71 =item pid - Product ID (PID).
73 =item production - if set true, uses the production server instead of the staging server.
79 @login_opt = qw( RID Username Password );
83 my $class = ref($proto) || $proto;
85 bless ($self, $class);
87 my $opt = $self->_lc_hash_or_hashref(@_);
88 $self->{$_} = $opt->{$_} for map lc($_), @login_opt;
90 if ( defined($opt->{'production'}) && $opt->{'production'} ) {
91 $self->{'url'} = 'https://secure.arteragroup.com/';
93 $self->{'url'} = 'http://staging.arteragroup.com/';
95 $self->{'url'} .= 'Wizards/wsapi/31/APIService.asmx';
97 $self->{'ua'} = LWP::UserAgent->new;
99 warn "\n$self created: ". Dumper($self) if $DEBUG;
104 sub _lc_hash_or_hashref {
106 my $opt = ref($_[0]) ? shift : {@_};
107 my $gratuitous = { map { lc($_) => $opt->{$_} } keys %$opt };
111 =item newTrial [ OPTIONS_HASHREF | OPTION => VALUE ... ]
113 Options can be passed as a hash reference or a list. Options are
116 Available options are:
120 =item email (required)
122 =item cname (required) - Customer's name
124 =item ref (required) - Reseller's own order reference
126 =item pid (required) - Artera Product ID
128 =item priceid (required) - Artera Price ID
130 =item aid - Affiliate ID number used when the Reseller wants to track some type of sales channel beneath them.
142 =item cid* - Country ID. Defaults to 2 (USA). Can be specified as a numeric CID or as an ISO 3166 two-letter country code or full name.
150 *These fields are optional, but must be supplied as a set.
152 Returns a hash reference with the following keys (these keys B<are>
157 =item id - This is the Result ID to indicate success or failure: 1 for success, anything else for failure
159 =item message - Some descriptive text regarding the success or failure
161 =item ASN - The Artera Serial Number
163 =item AKC - The Artera Key Code
165 =item TrialID - The Artera Trial Number
167 =item Ref - The Reseller Reference
169 =item CustomerID - Artera's CustomerID
171 =item TrialLength - Trial Length
177 my $opt = $self->_lc_hash_or_hashref(@_);
178 $self->_newX('Trial', $opt);
181 =item newOrder [ OPTIONS_HASHREF | OPTION => VALUE ... ]
183 Available options are the same as B<newTrial>. Additionally the I<asn> and
184 I<akc> fields may be specified to convert a trial to an order.
190 my $opt = $self->_lc_hash_or_hashref(@_);
191 push @{$opt->{'optional_params'}}, qw( ASN AKC );
192 $self->_newX('Order', $opt);
196 my( $self, $x, $opt ) = @_;
198 if ( defined($opt->{'cid'}) ) {
199 $opt->{'cid'} = $self->_country2cid($opt->{'cid'});
201 $opt->{'cid'} = 2 if grep defined($_), qw(Add1 Add3 Add4 Zip);
204 push @{$opt->{'required_params'}},
205 qw( Email CName Ref PID PriceID );
206 push @{$opt->{'optional_params'}},
207 qw( AID Add1 Add2 Add3 Add4 Zip CID Phone Fax );
209 $self->_submit( "new$x", $opt );
256 '' => 43, #HERZEGOVINA
260 '' => 47, #MONTENEGRO
273 my( $self, $country ) = @_;
274 if ( $country =~ /^\s*(\d+)\s*$/ ) {
276 } elsif ( $country =~ /^\s*(\w\w)\s*$/ ) {
278 } elsif ( $country !~ /^\s*$/ ) {
279 $country2cid{country2code($country)};
285 =item statusChange [ OPTIONS_HASHREF | OPTION => VALUE ... ]
287 Options can be passed as a hash reference or a list. Options are
290 Available options are:
294 =item ASN (required) - Artera Serial Number
296 =item AKC (required) - Artera Key Code
298 =item StatusID (required) - Possible StatusID values are as follows:
302 =item 15 - Normal Unrestricted: re-enable a disabled Serial Number (e.g. a payment dispute has been resolved so the Serial Number needs to be re-enabled).
304 =item 16 - Disable: temporarily prohibit an end-user's serial number from working (e.g. there is a payment dispute, so you want to turn off the Serial Number until the dispute is resolved).
306 =item 17 - Terminate: permanently prohibit an end-user's Serial Number from working (e.g. subscription cancellation)
310 =item Reason - Reason for terminating
314 Returns a hash reference with the following keys (these keys B<are>
319 =item id - This is the Result ID to indicate success or failure: 1 for success, anything else for failure
321 =item message - Some descriptive text regarding the success or failure
329 my $opt = $self->_lc_hash_or_hashref(@_);
331 push @{$opt->{'required_params'}},
332 qw( ASN AKC StatusID );
333 push @{$opt->{'optional_params'}}, 'Reason';
335 $self->_submit('statusChange', $opt );
338 =item getProductStatus [ OPTIONS_HASHREF | OPTION => VALUE ... ]
340 Options can be passed as a hash reference or a list. Options are
343 Available options are:
347 =item ASN (required) - Artera Serial Number
349 =item AKC (required) - Artera Key Code
353 Returns a hash reference with the following keys (these keys B<are>
358 =item id - This is the Result ID to indicate success or failure: 1 for success, anything else for failure
360 =item message - On failure, descriptive text regarding the failure
362 =item StatusID (required) - Possible StatusID values are as follows:
366 =item 15 - Normal Unrestricted: re-enable a disabled Serial Number (e.g. a payment dispute has been resolved so the Serial Number needs to be re-enabled).
368 =item 16 - Disable: temporarily prohibit an end-user's serial number from working (e.g. there is a payment dispute, so you want to turn off the Serial Number until the dispute is resolved).
370 =item 17 - Terminate: permanently prohibit an end-user's Serial Number from working (e.g. subscription cancellation)
374 =item Description - Status description
380 sub getProductStatus {
383 my $opt = $self->_lc_hash_or_hashref(@_);
385 push @{$opt->{'required_params'}}, qw( ASN AKC );
387 my $result = $self->_submit('getProductStatus', $opt );
389 # munch results, present as flat list
390 $result->{$_} = $result->{'Status'}->{$_} foreach (qw(StatusID Description));
391 delete $result->{'Status'};
397 =item updateContentControl [ OPTIONS_HASHREF | OPTION => VALUE ... ]
399 Options can be passed as a hash reference or a list. Options are
402 Available options are:
406 =item ASN (required) - Artera Serial Number
408 =item AKC (required) - Artera Key Code
410 =item UseContentControl (required) - 0 for off, 1 for on
414 Returns a hash reference with the following keys (these keys B<are>
419 =item id - This is the Result ID to indicate success or failure: 1 for success, anything else for failure
421 =item message - Some descriptive text regarding the success or failure
427 sub updateContentControl {
430 my $opt = $self->_lc_hash_or_hashref(@_);
432 push @{$opt->{'required_params'}}, qw( ASN AKC UseContentControl );
434 $self->_submit('updateContentControl', $opt );
437 =item orderListByDate [ OPTIONS_HASHREF | OPTION => VALUE ... ]
446 my( $self, $method, $opt ) = @_;
447 my $ua = $self->{'ua'};
450 ( map { $_ => $self->{lc($_)} }
453 ( map { $_ => $opt->{lc($_)} }
454 @{$opt->{'required_params'}}
456 ( map { $_ => ( exists $opt->{lc($_)} ? $opt->{lc($_)} : '' ) }
457 @{$opt->{'optional_params'}}
460 warn "$self url $self->{url}/$method\n" if $DEBUG;
461 warn "$self request parameters: ". Dumper($param). "\n" if $DEBUG;
464 my $response = $ua->post( "$self->{'url'}/$method", $param );
466 warn "$self raw response: ". $response->content. "\n" if $DEBUG;
468 #unless ( $response->is_success ) {
469 # die $response->content;
472 my $xml = XMLin( $response->content );
473 warn "$self parsed response: ". Dumper($xml) if $DEBUG;
475 #warn "\n".$xml->{'message'}."\n" unless $xml->{'id'} == 1 or not $WARN;
485 orderListByDate is unimplemented.
489 <http://www.arteraturbo.com>
493 Ivan Kohler, E<lt>ivan-net-artera@420.amE<gt>
495 Freeside, open-source billing for ISPs: <http://www.sisd.com/freeside>
497 Not affiliated with Artera Group, Inc.
499 =head1 COPYRIGHT AND LICENSE
501 Copyright (C) 2004 Ivan Kohler
503 This library is free software; you can redistribute it and/or modify
504 it under the same terms as Perl itself.