<html><head><title>WebService::Hexonet::Connector::APIClient</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.35,
using Pod::Simple::PullParser v3.35,
under Perl v5.030001 at Thu Jul 16 08:59:57 2020 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u'
name="NAME"
>NAME</a></h1>
<p>WebService::Hexonet::Connector::APIClient - Library to communicate with the insanely fast <a href="https://www.hexonet.net" class="podlinkurl"
>HEXONET Backend API</a>.</p>
<h1><a class='u'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<p>This module helps to integrate the communication with the HEXONET Backend System.
To be used in the way:</p>
<pre> use 5.030;
use strict;
use warnings;
use WebService::Hexonet::Connector;
# Create a connection with the URL, entity, login and password
# Use " 1234 " as entity for the OT&E, and " 54 cd " for productive use
# Don't have a Hexonet Account yet? Get one here: www.hexonet.net/sign-up
# create a new instance
my $cl = WebService::Hexonet::Connector::APIClient->new();
# set credentials
$cl->setCredentials('test.user', 'test.passw0rd');
# or instead set role credentials
# $cl->setRoleCredentials('test.user', 'testrole', 'test.passw0rd');
# set your outgoing ip address (to be used in case ip filter settings is active)
$cl->setRemoteIPAdress('1.2.3.4');
# specify the HEXONET Backend System to use
# LIVE System
$cl->useLIVESystem();
# or OT&E System
$cl->useOTESystem();
# ---------------------------
# SESSION-based communication
# ---------------------------
$r = $cl->login();
# or if 2FA is active, provide your otp code by
# $cl->login(" 12345678 ");
if ($r->isSuccess()) {
# use saveSession for your needs
# to apply the API session to your frontend session.
# For later reuse (no need to specify credentials and otp code)
# within every request to your frontend server,
# rebuild the session by using reuseSession method accordingly.
# No need to provide credentials, no need to select a system,
# nor to provide a otp code further on.
$r = $cl->request({ COMMAND: 'StatusAccount' });
# further logic, further commands
# perform logout, you may check the result as shown with the login method
$cl->logout();
}
# -------------------------
# SESSIONless communication
# -------------------------
$r = $cl->request({ COMMAND: 'StatusAccount' });
# -------------------------------------
# Working with returned Response object
# -------------------------------------
# Display the result in the format you want
my $res;
$res = $r->getListHash());
$res = $r->getHash();
$res = $r->getPlain();
# Get the response code and the response description
my $code = $r->getCode();
my $description = $r->getDescription();
print "$code$description ";
# There are further useful methods that help to access data
# like getColumnIndex, getColumn, getRecord, etc.
# Check the method documentation below.</pre>
<p>See the documented methods for deeper information.</p>
<h1><a class='u'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>This library is used to provide all functionality to be able to communicate with the HEXONET Backend System.</p>
<h2><a class='u'
name="Methods"
>Methods</a></h2>
<dl>
<dt><a name="new"
><code>new</code></a></dt>
<dd>
<p>Returns a new <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance.</p>
<dt><a name="enableDebugMode"
><code>enableDebugMode</code></a></dt>
<dd>
<p>Activates the debug mode. Details of the API communication are put to STDOUT. Like API command, POST data, API plain-text response. Debug mode is inactive by default. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="disableDebugMode"
><code>disableDebugMode</code></a></dt>
<dd>
<p>Deactivates the debug mode. Debug mode is inactive by default. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="getPOSTData(_$command,_$secured_)"
><code>getPOSTData( $command, $secured )</code></a></dt>
<dd>
<p>Get POST data fields ready to use for HTTP communication based on LWP::UserAgent. Specify the API command for the request by $command. Specify if password data has to be replaced with asterix to secure it for output purposes by $secured. Optional. This method is internally used by the request method. Returns a hash.</p>
<dt><a name="getProxy"
><code>getProxy</code></a></dt>
<dd>
<p>Returns the configured Proxy URL to use for API communication as string.</p>
<dt><a name="getReferer"
><code>getReferer</code></a></dt>
<dd>
<p>Returns the configured HTTP Header `Referer` value to use for API communication as string.</p>
<dt><a name="getSession"
><code>getSession</code></a></dt>
<dd>
<p>Returns the API session in use as string.</p>
<dt><a name="getURL"
><code>getURL</code></a></dt>
<dd>
<p>Returns the url in use pointing to the Backend System to communicate with, as string.</p>
<dt><a name="getUserAgent"
><code>getUserAgent</code></a></dt>
<dd>
<p>Returns the user-agent string.</p>
<dt><a name="getVersion"
><code>getVersion</code></a></dt>
<dd>
<p>Returns the SDK version currently in use as string.</p>
<dt><a name="saveSession(_$sessionhash_)"
><code>saveSession( $sessionhash )</code></a></dt>
<dd>
<p>Save the current API session data into a given session hash object. This might help you to add the backend system session into your frontend session. Use reuseSession method to set a new instance of this module to that session. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="reuseSession(_$sessionhash_)"
><code>reuseSession( $sessionhash )</code></a></dt>
<dd>
<p>Reuse API session data that got previously saved into the given session hash object by method saveSession. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="setURL(_$url_)"
><code>setURL( $url )</code></a></dt>
<dd>
<p>Set a different backend system url to be used for communication. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="setOTP(_$otpcode_)"
><code>setOTP( $otpcode )</code></a></dt>
<dd>
<p>Set your otp code. To be used in case of active 2FA. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="setProxy(_$proxy_)"
><code>setProxy( $proxy )</code></a></dt>
<dd>
<p>Set the Proxy URL to use for API communication. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="setReferer(_$referer_)"
><code>setReferer( $referer )</code></a></dt>
<dd>
<p>Set the HTTP Header `Referer` value to use for API communication. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="setSession(_$sessionid_)"
><code>setSession( $sessionid )</code></a></dt>
<dd>
<p>Set the API session id to use. Automatically handled after successful session login based on method login or loginExtended. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="setRemoteIPAddress(_$ip_)"
><code>setRemoteIPAddress( $ip )</code></a></dt>
<dd>
<p>Set the outgoing ip address to be used in API communication. Use this in case of an active IP filter setting for your account. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="setCredentials(_$user,_$pw_)"
><code>setCredentials( $user, $pw )</code></a></dt>
<dd>
<p>Set the credentials to use in API communication. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="setRoleCredentials(_$user,_$role,_$pw)"
><code>setRoleCredentials( $user, $role, $pw)</code></a></dt>
<dd>
<p>Set the role user credentials to use in API communication. NOTE: the role user specified by $role has to be directly assigned to the specified account specified by $user. The specified password $pw belongs to the role user, not to the account. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="setUserAgent(_$str,_$rv,_$modules_)"
><code>setUserAgent( $str, $rv, $modules )</code></a></dt>
<dd>
<p>Set a custom user agent header. This is useful for tools that use our SDK. Specify the client label in $str and the revision number in $rv. Specify further libraries in use by array $modules. This is optional. Entry Format: "modulename/version". Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining .</p>
<dt><a name="login(_$otpcode_)"
><code>login( $otpcode )</code></a></dt>
<dd>
<p>Perform a session login. Entry point for the session-based communication. You may specify your OTP code by $otpcode. Returns an instance of <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AResponse" class="podlinkpod"
>WebService::Hexonet::Connector::Response</a>.</p>
<dt><a name="loginExtended(_$params,_$otpcode_)"
><code>loginExtended( $params, $otpcode )</code></a></dt>
<dd>
<p>Perform a session login. Entry point for the session-based communication. You may specify your OTP code by $otpcode. Specify additional command parameter for API command " StartSession " in Hash $params. Possible parameters can be found in the <a href="https://github.com/hexonet/hexonet-api-documentation/blob/master/API/USER/SESSION/STARTSESSION.md" class="podlinkurl"
>API Documentation for StartSession</a>. Returns an instance of <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AResponse" class="podlinkpod"
>WebService::Hexonet::Connector::Response</a>.</p>
<dt><a name="logout"
><code>logout</code></a></dt>
<dd>
<p>Perfom a session logout. This destroys the API session. Returns an instance of <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AResponse" class="podlinkpod"
>WebService::Hexonet::Connector::Response</a>.</p>
<dt><a name="request(_$command_)"
><code>request( $command )</code></a></dt>
<dd>
<p>Requests the given API Command $command to the Backend System. Returns an instance of <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AResponse" class="podlinkpod"
>WebService::Hexonet::Connector::Response</a>.</p>
<dt><a name="requestNextResponsePage(_$lastresponse_)"
><code>requestNextResponsePage( $lastresponse )</code></a></dt>
<dd>
<p>Requests the next response page for the provided api response $lastresponse. Returns an instance of <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AResponse" class="podlinkpod"
>WebService::Hexonet::Connector::Response</a>.</p>
<dt><a name="requestAllResponsePages(_$command_)"
><code>requestAllResponsePages( $command )</code></a></dt>
<dd>
<p>Requests all response pages for the specified command. NOTE: this might take some time. Requests are not made in parallel! Returns an array of instances of <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AResponse" class="podlinkpod"
>WebService::Hexonet::Connector::Response</a>.</p>
<dt><a name="setUserView(_$subuser_)"
><code>setUserView( $subuser )</code></a></dt>
<dd>
<p>Activate read/write Data View on the specified subuser account. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="resetUserView"
><code>resetUserView</code></a></dt>
<dd>
<p>Reset the data view activated by setUserView. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="useDefaultConnectionSetup"
><code>useDefaultConnectionSetup</code></a></dt>
<dd>
<p>Use the Default Setup to connect to our backend systems. This is the default! Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="useHighPerformanceConnectionSetup"
><code>useHighPerformanceConnectionSetup</code></a></dt>
<dd>
<p>Use the High Performance Connection Setup to connect to our backend systems. This is not the default! Read README.md for Details. Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="useLIVESystem"
><code>useLIVESystem</code></a></dt>
<dd>
<p>Use the LIVE Backend System as communication endpoint. Usage may lead to costs. BUT - are system is a prepaid system. As long as you don't have charged your account, you cannot order. This is the default! Returns the current <a href="http://search.cpan.org/perldoc?WebService%3A%3AHexonet%3A%3AConnector%3A%3AAPIClient" class="podlinkpod"
>WebService::Hexonet::Connector::APIClient</a> instance in use for method chaining.</p>
<dt><a name="_flattenCommand(_$cmd_)"
><code>_flattenCommand( $cmd )</code></a></dt>
<dd>
<p>Private method. Converts all keys of the given hash into upper case letters and flattens parameters using nested arrays to string parameters. Returns the new command.</p>
<dt><a name="_autoIDNConvert(_$cmd_)"
><code>_autoIDNConvert( $cmd )</code></a></dt>
<dd>
<p>Private method. Converts all affected parameter values to punycode as our API only works with punycode domain names, not with IDN. Returns the new command.</p>
</dd>
</dl>
<h1><a class='u'
name="LICENSE_AND_COPYRIGHT"
>LICENSE AND COPYRIGHT</a></h1>
<p>This program is licensed under the <a href="https://raw.githubusercontent.com/hexonet/perl-sdk/master/LICENSE" class="podlinkurl"
>MIT License</a>.</p>
<h1><a class='u'
name="AUTHOR"
>AUTHOR</a></h1>
<p><a href="https://www.hexonet.net" class="podlinkurl"
>HEXONET GmbH</a></p>
<!-- end doc -->
</body></html>