The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Net-TPP-0.02
River stage zero No dependents
/ Net::TPP

NAME

Net::TPP - A simple perl interface to the TPP API. http://www.tppwholesale.com.au/api.php

SYNOPSIS

use Net::TPP;
use warnings;
use strict;

# Create $tpp object and set login details
my $tpp = Net::TPP->new(
    AccountNo => '12345',
    UserId => 'Foo',
    Password => 'Bar'
);

# Register a domain if it is available
if ($tpp->can_register_domain(Domain => 'tppwholesale.com.au')) {
    my $domain_order_details = $tpp->register_domain(
        Domain => 'tppwholesale.com.au',
        # Other values ..
    );
}

# Check order status
my $order_status = $tpp->get_order_status(OrderID => 1234567, Domain => 'tppwholesale.com.au');

# Check details of a domain you own
my $domain_details = $tpp->get_domain_details(Domain => 'tppwholesale.com.au');

DESCRIPTION

Net::TPP is a simple module to provide an object-oriented interface to use the TPP API with your TPP account for various domain functions - registering, transferring & managing domains, etc.

METHODS (main)

new

Instantiate a new TPP object

my $tpp = Net::TPP->new(
    AccountNo => '12345',
    UserId => 'Foo',
    Password => 'Bar'
);

call

Call a specific API operation directly. Consult TPP API documention for the parameters required. Note that authentication parameters will be passed in automatically (such as SessionID)

my $domain_details = $tpp->call(
    Mode   => 'QUERY',
    Type   => 'Domains',
    Object => 'Domain',
    Action => 'Details',
    Domain => 'tppwholesale.com.au'
);

This method (and the convenience methods below that use this method) will return a hashref when successful. The hashref content may change depending on which specific call is made, however it typically contains:

{
    OK         => 1,        # A true value if the call succeeded.
    output     => $VAR,     # A string or a hashref with relevant output, depending on what call was made
    output_raw => 'string'  # A string of the raw response from TPP
}

error

Return the last error that occured. If necessary, you can check the error code with $tpp->{error_code}

METHODS (convenience)

There are a number of convenience methods with names that are fairly self-descriptive. These methods simply execute the call method with the appropriate parameters.

login

This method does not really need to be called. It will be called automatically by the object if login is required.

get_domain_details

Returns various details about the domain you own in a hash reference in {output}.

my $domain_details = $tpp->get_domain_details(Domain => 'tppwholesale.com.au');
if ($domain_details && $domain_details->{OK}) {
    printf "This is the expiry date %s\n",$domain_details->{output}->{ExpiryDate};
    printf "Here are the nameservers %s\n",join(', ',@{$domain_details->{output}->{Nameserver}});
}

get_order_status

Returns information about an order you have previously placed, perhaps for a domain registration or a transfer.

my $order_status = $tpp->get_order_status(OrderID => '1234567', Domain => 'tppwholesale.com.au');

print Dumper($order_status->{output});

# Example content of {output} hashref:

# # Pending transfer:
# '60xxxxx' => {  # This is the OrderID passed as input
#     'status' => 'OK',
#     'message' => 'Scheduled,transfer requested (awaiting registry response)'
# },
# 'domain.org' => { # This is the Domain passed as input
#     'status' => 'OK',
#     'message' => 'icannTransfer2,Scheduled,transfer requested (awaiting registry response)'
# }
#
# # Completed transfer
# '60xxxxx' => {
#     'status' => 'OK',
#     'message' => 'Complete'
# },
# 'domain.org' => {
#     'status' => 'OK',
#     'message' => ''
# }
# 
# # Or if only order id was specified, output is not be divided into domain and order id. It will just be:
# {
#     'status' => 'OK',
#     'message' => 'Complete'
# };

can_renew_domain

Check if a domain can be renewed.

my $can_renew_domain = $tpp->can_renew_domain(Domain => 'tppwholesale.com.au');
print Dumper($can_renew_domain);

# Example output

# 'output' => {
#     'Maximum' => '2',  # Maximum years for which you can renew
#     'ExpiryDate' => '2013-08-06',
#     'Minimum' => '2'   # Minimum years
# }

renew_domain

Renew a domain you own with TPP that is due to expire soon.

$tpp->renew_domain(Domain => 'tppwholesale.com.au', Period => 2); # Renew for 2 years

can_register_domain

Check if a domain is available to be registered

if ($tpp->can_register_domain(Domain => 'tppwholesale.com.au')) {
    print "Yes we can register this domain\n";
}

register_domain

Register a domain. There are many required fields, it's best to consult the TPP API documentation.

my $results = $tpp->register_domain(
    Domain => 'tppwholesale.com.au',
    Period => 2,
    # AccountOption - Default value (if omitted) creates a new account rather than specify an AccountID.
    OwnerContactID          => 'xxxxxx', A contact ID that you have set up previously.
    AdministrationContactID => 'xxxxxx', A contact ID that you have set up previously.
    BillingContactID        => 'xxxxxx', A contact ID that you have set up previously.
    TechnicalContactID      => 'xxxxxx', A contact ID that you have set up previously.
    Host                    => [qw(ns1.tppwholesale.com.au ns2.tppwholesale.com.au)], # Name Servers
    RegistrantName          => 'BUSINESS NAME PTY LTD', # Legal entity
    RegistrantID            => 'xxxxxxxxxxx', #ABN/ACN etc
    RegistrantIDType        => 2,  # ABN in this case.
    EligibilityID           => 'xxxxxxxxxxx', # Establish eligibility for the domain name
    EligibilityIDType       => 12, # ABN in this case
    EligibilityType         => 5,  # Company in this case
    EligibilityReason       => 2,  # Close and substantial connection between the domain name and the operations of your Entity
);

print Dumper($results);

# $VAR1 = {
#     # ...
#     'OK' => 1,
#     'output' => '1234567', # Order number
# };

can_transfer_domain

Check if a domain can be transferred

my $can_transfer_domain = $tpp->can_transfer_domain(Domain => 'tppwholesale.com.au');

if ($can_transfer_domain) {
    print "Yes we can transfer this domain\n";
    print Dumper($can_transfer_domain);

    # 'output' => {
    #     'RequirePassword' => '1'
    # }
    #
    # # Or different output with a DomainPassword specified:
    # output => {
    #     'Maximum' => '10',
    #     'Owner' => 'Business X Limited',
    #     'status' => 'OK',
    #     'ExpiryDate' => '2013-10-01',
    #     'Minimum' => '',
    #     'OwnerEmail' => 'email@address',
    # };
}

transfer_domain

Transfer a domain from another registrar to TPP under your account.

my $domain_transfer = $tpp->transfer_domain(
    Domain                  => 'tppwholesale.com.au',
    DomainPassword          => '12345678',
    OwnerContactID          => 1234567,
    AdministrationContactID => 1234567,
    TechnicalContactID      => 1234567,
    BillingContactID        => 1234567,
);

print Dumper($domain_transfer);

# Example output. - note that this might give an OK even though the domain password is wrong
# output => {
#   ...
#   'OK' => 1,
#   'output' => '61xxxxx' # Order ID
# };

Note that no option exists to change the name servers as part of the transfer. Name server changes need to be made before or after the transfer.

update_hosts

Add name servers to the list of current name servers for a domain. Note that you may want to use replace_hosts instead of this method.

$tpp->update_hosts(
    Domain   => 'tppwholesale.com.au',
    AddHost => [qw(ns3.tppwholesale.com.au ns4.tppwholesale.com.au)],
);

update_name_servers

An alias for update_hosts

replace_hosts

Similar to update_hosts except that the current name servers will be removed from the domain first. If required, it will also unlock a domain temporarily in order to set these name servers.

$tpp->replace_hosts(
    Domain   => 'tppwholesale.com.au',
    AddHost => [qw(ns3.tppwholesale.com.au ns4.tppwholesale.com.au)],
);

Note that this simply calls the UpdateHosts operation with the extra parameter: RemoveHost => 'ALL'

replace_name_servers

An alias for replace_hosts

lock_domain

This will lock the domain within TPP. Note that name servers cannot be updated while domains are locked, however replace_hosts will unlock if necessary.

unlock_domain

This will unlock the domain within TPP. Note that name servers cannot be updated while domains are locked, however replace_hosts will unlock if necessary.

create_contact

Create a contact under your TPP account.

$tpp->create_contact(
    FirstName        => 'Person',
    LastName         => 'OfInterest',
    Address1         => '123 Fake St',
    City             => 'Sydney',
    Region           => 'NSW',
    PostalCode       => '2000',
    CountryCode      => 'AU',
    PhoneCountryCode => '61',
    PhoneAreaCode    => '02',
    PhoneNumber      => '99999999',
    Email            => 'email@address',
);

# Example output:
# {
#     ..
#     'OK' => 1,
#     'output' => '1234567' # Order number
# };

update_contact

Update an existing contact under your TPP account for a specific domain.

$tpp->update_contact(
    Domain => 'tppwholesale.com.au',
    TechnicalContactID => 1234567,
);

CAVEATS

no test mode

TPP have confirmed that test-mode does not work on their system, despite mentions in some versions of the documentation. This makes it difficult to properly test all usage cases, and as such only major functions have been tested.

no ip lock down

The IP lockdown is not enabled by default - no IP address needs to be specified for use with the API. TPP have confirmed, however, that they lock an IP when 'the system detects any threat from a specific IP'

VERSION

0.02

AUTHOR

Matt Vink <matt.vink@gmail.com>

LICENSE AND COPYRIGHT

Copyright 2013 Matt Vink, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This module comes without warranty of any kind.