ReplixFax OutBound Fax API

ReplixFax Perl SOAP API Tutorial

Using the ReplixFax Cloud Service to send faxes is straightforward. All you need is a valid username and password, a destination fax number and a document to be sent as the fax. This tutorial describes the steps to create a Perl application that sends a fax using the ReplixFax SOAP API. The tutorial is on Windows, but the same code should work on a UNIX system.

You can Download the completed tutorial or follow the steps below.

Requirements

SOAP-Lite library

Sending a Fax

Open a command prompt to a folder called “c:\tutorial”. Make sure the Perl bin folder is in your path.

Create a tutorial.pl file

Use notepad or any other text editor to create the tutorial.pl file. Add the following code. You should replace <organization>, <username> and <password> with your credentials.

use SOAP::Lite;
use Data::Dumper;
use MIME::Base64;

use strict;
my $apiurl =    'https://api.rpxtest.com/softlinx/replixfax/wsapi'; # URL to the web services API
my $login =     '<username>';
my $password =  '<password>';
my $realm =  '<organization>';
my $soapAction = "http://www.softlinx.com/wsapi/op=SendFax/ver=15"; # soapAction header must contain API name and version

my $faxnumber = "<fax number>"; # fax number to send to
my $filename =  "<filename>"; # attachment to send
my $filetype =  "pdf"; # content type of $file

$soapURL="https://api.rpxtest.com/softlinx/replixfax/wsapi";
$client = new SoapClient($soapURL);

You can change $apiurl after testing to point to production: https://api.rpxfax.com/softlinx/replixfax/wsapi

Create a SOAP::Lite client

my $client = SOAP::Lite
    -> proxy($apiurl)
    -> ns('http://www.softlinx.com/ReplixFax', 'rpx')
    -> on_action(sub { qq("$soapAction") });
$client -> encodingStyle('');

Now create a new authentication variable:

my ($auth) = SOAP::Data->name('Authentication' => \SOAP::Data->value(
                                  SOAP::Data->name('Login' => $login)->type(''),
                                  SOAP::Data->name('Password' => encode_base64(>$password))->type(''),
                                  SOAP::Data->name('PasswordSecurity' => 'base64')->type(''),
                  SOAP::Data->name('Realm'=>$realm)->type('')));

Create a variable for the fax number:

my ($rcpt) = SOAP::Data->name('FaxRecipient' => \SOAP::Data->value(
                                  SOAP::Data->name('FaxNumber'=>$faxnumber)->type('')))

Create a variable for the fax content:

my $filedata = '';
{
    open (FILE, $filename) || die "open $filename $!";
    binmode FILE;
    my $chunk;
    while(read(FILE, $chunk, 1024))
    { 
    $filedata .= $chunk;
    }
    close FILE;
}

my ($att) = SOAP::Data->name('Attachment' => \SOAP::Data->value(
                                 SOAP::Data->name('ContentType' => $filetype)->type(''),
                                 SOAP::Data->name('FileName' => $filename)->type(''),
                                 SOAP::Data->name('AttachmentContent')->type(base64 => $filedata)));

Make a SendFax Request

When making any ReplixFax web service call, you must pass a corresponding input parameter. Since we are going to send a fax, we need to create a SendFaxInput object. This object will be an array that has keys that map to the required information for the SOAP request.

To send the fax request to the server, call SendFax and pass in the SendFaxInput object. As mentioned before all ReplixFax service calls require a corresponding input object. They also return a corresponding output object. In this case, SendFaxOutput, which is returned in the $res variable.

my (@args) = ($auth, $rcpt, $att);
my $res = $client->call('SendFax' => 
                        SOAP::Data->name('SendFaxInput' => \SOAP::Data->value(@args)));

The SendFaxOutput object will contain a status code and optional message. It will also contain the fax job IDs created. There will be a fax job id for each recipient. Since we only specified a single recipient, we only have one fax job id.

if($res->fault)
{
    if(ref $res)
    {
        print "fault-code:   " . $res->valueof('//RequestFault/FaultCode'), "\n";
        print "fault-string: " . $res->valueof('//RequestFault/FaultText'), "\n";
    }
    else
    {
        print $client->transport->status, "\n";
    }
}
else
{
    print "request-status-code=", $res->valueof('//RequestStatus/StatusCode'), "\n";
    print "request-status-text=", $res->valueof('//RequestStatus/StatusText'), "\n";

    print "faxid=", join(",", $res->valueof('//FaxInfo/FaxId')), "\n";
}

Run tutorial.pl

From a browser access the tutorial.pl file.

If all went well, you should see a fax id of a newly created fax request.

If you have any errors, potentially you are not using the correct credentials or the path to the attachment is incorrect.

Check the status of the Outgoing Fax

When a fax request is made, it must be processed by the system and then it is scheduled to be faxed. The system processing includes converting all document files to tiff and generating cover pages if a ReplixFax template cover page is being used. When a fax is ready to be sent, potentially the recipient fax machine (or server) is busy and does not have any open lines. Therefore it is difficult to determine when a fax will be successfully sent and received by the recipient fax machine or server.

In order to check the status of a fax, you need to query the system. Look at the Query Sent Faxes sample to see how to do this.

Next steps

The Perl samples show how to perform other common Fax tasks. If you have questions about this tutorial or other API related items, contact Softlinx support.

ReplixFax Tutorials