Introduction to InterFAX

Introduction to InterFAX

Introduction:

InterFAX is an online commercial subscription-based fax services that allows developers to integrate fax services to send and receive fax very easily and cost-effectively. It accepts files in all office formats. It is the only electronic fax company, which is 100 % PCI compliant. Interfax providing many ways to integrate fax in your application.

Here I will explain how you can use InterFAX services in your web application using PHP. There are two ways to integrate InterFAX in web application.

  1. InterFAX PHP library
  2. SOAP/REST API

 1. InterFAX PHP library

 You can directly download the library from GitHub. It is very easy to integrate in the code. By clicking here, you can download the library. Here, you can find various examples of FAX operations.

Send Fax

This is the example of sending a single fax.

<?php
require_once(‘vendor/autoload.php’);
use Interfax\Client;
$interfax = new Client([‘username’ => ‘username’, ‘password’ => ‘password’]);
$fax = $interfax->deliver([‘faxNumber’ => ‘0019999999999’, ‘file’ => ‘sample-pdf.pdf’]);
// get the latest status:
$fax->refresh()->status;  // Pending if < 0. Error if > 0
// Simple polling
while ($fax->refresh()->status < 0) {
sleep(5)
}
?>

You must have to define client before executing any operation with InterFAX. It is using 12-factor apps principal. You can set it directly or via environment variable.

$client = new Interfax\Client([‘username’ => ‘…’, ‘password’ => ‘…’]);// Alternative: will utilise environment variables:
// * INTERFAX_USERNAME
// * INTERFAX_PASSWORD
$client = new Interfax\Client();

With client, you can also do various operations that are listed below:

Balance

echo $client->getBalance();

Fax

Deliver method is used to send fax. You can send multiple files using deliver method.

$client = new Interfax\Client([‘username’ => ‘…’, ‘password’ => ‘…’]);
$fax = $client->deliver([
‘faxNumber’ => ‘+442086090368’,
‘file’ => __DIR__ . ‘/../tests/Interfax/test.pdf’
]);

Outbound Property

Outbound property is used to do many operations like: get list, get completed list, get record, get image, cancel fax, search, resend fax. It can be accessed like below.

$faxes = $client->outbound;

Inbound Property

Inbound property is used to get information about incoming fax/email like: get list, get record, get image, get emails, mark as read, resend to email. It can be accessed like below.

$faxes = $client->inbound;

2. SOAP/REST API

InterFAX is also providing REST/SOAP API. SOAP/REST API are best way to interact with third party application. You can use SOAP/REST API, if you do not want to depend on any library. Here, I will give you a brief explanation using REST API.

Before using REST API, you need to make sure that CURL is enabled in your php version.

Below URL is used to interact with InterFAX:

https://rest.interfax.net/outbound/faxes

This service is using HTTP basic authentication. You have to submit Username and Password in a header within every HTTP call. There is no authenticated session, which means you must have to authenticate every call.

Various examples given below for different operation:

Send Fax:

$postFields = array(‘data’ => ‘filePath’.$File);
$URL   = “https://rest.interfax.net/outbound/faxes?faxNumber=”.        $params[‘FaxNumber’] .”&reference=”.urlencode($params[‘Subject’]);
$ch           =   curl_init($URL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_USERPWD, $params[‘User’].”:”.$params[‘Password’]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(‘Content-Type: application/pdf’));
$response   =   curl_exec($ch);
$error      =   curl_error($ch);

In $response variable, you can get id and other properties.

Arguments

Name Type Comments Default value on POST
faxNumber FaxNumber A single fax number, e.g: +1-212-3456789. Mandatory Value
contact String A name or other reference. The entered string will appear: (1) for reference in the outbound queue; (2) in the outbound fax header, if headers are configured; and (3) in subsequent queries of the fax object. Null
postponeTime DateTime Time to schedule the transmission. No postponement
retriesToPerform Number Number of transmission attempts to perform, in case of fax transmission failure. Wil take from control panel settings
csid String (up to 20 characters) Sender CSID. Wil take from control panel settings
pageHeader String The fax header text to insert at the top of the page. Enter N to override any control panel settings. Wil take from control panel settings
reference String (up to 60 characters) Provide your internal ID to a document. This parameter can be obtained by status query, but is not included in the transmitted fax message. Null
replyAddress Email E-mail address to which feedback messages will be sent. Wil take from control panel settings
pageSize String a4, letter, legal, or b4. Wil take from control panel settings
fitToPage String scale or no scale. Scale (enlarge or reduce) an image file to the given page size. Wil take from control panel settings
pageOrientation String portrait or landscape. Wil take from control panel settings
Resolution String standard or fine. Documents rendered as fine may be more readable but take longer to transmit (and may therefore be costlier). Wil take from control panel settings
rendering String greyscale or bw. Determines the rendering mode.  bw is recommended for textual, black & white documents, while greyscale is better for greyscale text and for images. Wil take from control panel settings

Get Fax List:

$URL = “https://rest.interfax.net/outbound/faxes?limit=10&sortOrder=asc”;
$ch = curl_init($URL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_USERPWD, $params[‘User’].”:”.$params[‘Password’]);
$response   =   curl_exec($ch);
$error      =   curl_error($ch);

Arguments

Name Type Comments Default
limit Number No. of transaction to return 25
lastId String Return results from this ID onwards (it will not include this ID). For Pagination purpose. Infinite when sortOrder is desc; zero when sortOrder is asc.
sortOrder String asc or desc. Sort by fax ID. desc
userId String Enables a “primary” user to query for other account users’ faxes. Current user (provided in credentials)

In response, it will give full detailed array which includes id, uri, status (0 = Success, less than 0 = In Process, greater than 0 = Error), userid, pagesSent, completionTime, remoteCSID, duration, priority, units, costPerUnit, attemptsMade, pageSize, pageOrientation, PageResolution, rendering, pageHeader, submitTime, subject, destinationFax, replyEmail, pagesSubmitted, senderCSID, attemptsToPerform, contact.

Get Completed List:

$URL = “https://rest.interfax.net/outbound/faxes/completed?ids={list of numbers}”;
$ch  = curl_init($URL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_USERPWD, $params[‘User’].”:”.$params[‘Password’]);
$response   =   curl_exec($ch);
$error      =   curl_error($ch);

Arguments

Name Type Comments Default
ids Number Comma-delimited list of fax id’s to retrieve, if they have completed. Mandatory

Response: If successful, it will give you complete list of structure returns like “Get Fax List”.

Get Fax Record:

$URL = ” https://rest.interfax.net/outbound/faxes/{id}”;
$ch  = curl_init($URL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_USERPWD, $params[‘User’].”:”.$params[‘Password’]);
$response   =   curl_exec($ch);
$error      =   curl_error($ch);

Arguments

Name Type Comments Default
ids Number The transaction ID of the fax for which to retrieve data. Mandatory

Response: If successful, it will give you complete list of structure returns like “Get Fax List”.

Cancel Fax:

Note: This will work only if faxes awaiting sending but not on faxes which are actively sending.

$URL = “https://rest.interfax.net/outbound/faxes/{id}/cancel”;
$ch  = curl_init($URL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_USERPWD, $params[‘User’].”:”.$params[‘Password’]);
$response   =   curl_exec($ch);
$error      =   curl_error($ch);

Arguments

Name Type Comments Default
ids Number ID of the fax to be cancelled. Note: This operation may be applied to single faxes or to individual faxes in a batch. Mandatory

Response: Standard HTTP response will come.

Search Fax:

$URL   = ” https://rest.interfax.net/outbound/search?ids={list of numbers}&reference={string}&dateFrom={datetime}&dateTo={datetime}&status={number}&userId={string}&faxNumber={faxnumber}&sortOrder={asc|desc}&offset={number}&limit={limit}”;
$ch           =   curl_init($URL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_USERPWD, $params[‘User’].”:”.$params[‘Password’]);
$response   =   curl_exec($ch);
$error      =   curl_error($ch);

Arguments

Name Type Comments Default
ids List of numbers List of comma-delimited fax IDs None
reference String The ‘reference’ parameter entered at submit time None
dateFrom DateTme Lower bound of date range from which to return faxes No Limit
dateTo DateTme Upper bound of date range from which to return faxes No Limit
status String Completed = return only completed faxes, Success = return only successfully-completed faxes, Failed = return only failed faxes, Inprocess = return only faxes in process. Specific value from status code list All
userId List Of String For specific user. None
faxNumber FaxNumber For specific destination fax number None
limit Number No. of transaction to return 25
offset Number Skip this many records 0

Response: If successful, it will give you complete list of structure returns like “Get Fax List”.

Resend Fax:

$URL   = “https://rest.interfax.net/outbound/faxes{id}/resend?faxNumber={faxnumber}”;
$ch           =   curl_init($URL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_USERPWD, $params[‘User’].”:”.$params[‘Password’]);
curl_setopt($ch, CURLOPT_POSTFIELDS, ”);
$response   =   curl_exec($ch);
$error      =   curl_error($ch);

Arguments

Name Type Comments Default
id Number The ID of the fax to be resent. Mandatory
faxNumber faxNumber The destination fax number to which to resend this transaction. Mandatory

Response: If successful, it will give Header Location with newly created fax resource.

There are other operations also accessible like Hide Fax, Send Batches, Upload Document, and Get Outbound Credit.

InterFAX PHP library is also using REST API. To avoid unnecessary execution of code or to build your custom script for sending faxes REST APIs are best. By clicking here, you will see each service and its endpoint.

The following two tabs change content below.
Avatar photo
My Twitter profile

Nirav Bhut

Sr. Software Developer (PHP) at Dev Information Technology Ltd.
I'm a Zend Framework 2 expert, writing and integrating APIs, and executing complex queries with over 5 years of experience. I am currently working as a Senior Software Developer at Dev Information Technology Ltd. I'm crazy about the user experience and I'm ready to provide you with the best solution available. I'm the type of person who learns new things and makes extra efforts every day to learn.
Avatar photo
My Twitter profile

Latest posts by Nirav Bhut (see all)

Written by

Digital Services, eCommerce Storefronts 1 Comment

One thought on “Introduction to InterFAX”

Leave a Reply

Your email address will not be published. Required fields are marked *