search

interfax / interfax-java

Fax send and receive in Java with the InterFAX REST API
https://www.interfax.net/en/dev/java
MIT License
5 stars 9 forks source link
fax fax-image hipaa inbound interfax interfax-api java library online-fax outbound receive sdk send

readme

InterFAX Java Library

Build Status Maven Central

Installation | Getting Started | Usage | Contributing | License

Send and receive faxes in Java with the InterFAX REST API.

Installation

Use of the library requires Java 11 or higher and can be done via one of the following approaches.

Include as maven dependency

<dependency>
  <groupId>net.interfax</groupId>
  <artifactId>api-client</artifactId>
  <version>0.17</version>
</dependency>

Download jar and include in application classpath

Download the latest jar from the Maven central repository and place it in your application classpath.

Getting started

To send a fax from a PDF file:

java.io.File file = new File(absoluteFilePath);
InterFAX interFAX = new DefaultInterFAXClient("username", "password");
APIResponse apiResponse = interFAX.sendFax(faxNumber, file);

Usage

Client | Account | Outbound | Inbound | Documents

Client

The client follows the 12-factor apps principle and can be either set directly or via environment variables.

// Initialize using parameters
InterFAX interFAX = new DefaultInterFAXClient("username", "password");

// Alternative 1: Initialize using environment variables
// Ensure following env vars are initialized with values of your API credentials
// * INTERFAX_USERNAME
// * INTERFAX_PASSWORD
InterFAX interFAX = new DefaultInterFAXClient();

// Alternative 2: Initialize using yaml file
// Create a file called `interfax-api-credentials.yaml` with the following contents, replacing the value of `username`
// and `password` fields with those of your API credentials.
//   username: "api-username"
//   password: "api-password"
InterFAX interFAX = new DefaultInterFAXClient();

All connections are established over HTTPS.

Account

Credit balance

Determine the remaining faxing credits in your account

InterFAX interFAX = new DefaultInterFAXClient();
Double balance = interFAX.getAccountCredits();

More: documentation

Outbound

Send | Get list | Get completed list | Get record | Get image | Cancel fax | Search | Hide fax

Send Fax

Submit a fax to a single destination number.

There are a few ways to send a fax. One way is to directly provide a file path or url.

// with an absoluteFilePath
java.io.File file = new File(absoluteFilePath);
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.sendFax(faxNumber, file);

// with an inputstream
InputStream[] inputStreams = {inputStream};
String[] mediaTypes = {"application/pdf"};
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.sendFax(faxNumber, inputStreams, mediaTypes);

// with a URL
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.sendFax(faxNumber, "https://s3.aws.com/example/fax.html");

InterFAX supports over 20 file types including HTML, PDF, TXT, Word, and many more. For a full list see the Supported File Types documentation.

The returned object is a APIResponse with the statusCode and responseBody of the request submitted to InterFAX.

To send multiple files just pass in an array of files or inputstreams

// using Files
public APIResponse sendFax(final String faxNumber, 
                           final File[] filesToSendAsFax) 
                           throws IOException;

// using Inputstreams
public APIResponse sendFax(final String faxNumber,
                           final InputStream[] streamsToSendAsFax,
                           final String mediaTypes[]) throws IOException;

All requests to send a fax can include the following Options: contact, postponeTime, retriesToPerform, csid, pageHeader, reference, pageSize, fitToPage, pageOrientation, resolution, rendering set via SendFaxOptions class

Get Outbound Fax List

Get a list of recent outbound faxes (which does not include batch faxes).

InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.getFaxList();

Using additional Options: limit, lastId, sortOrder, userId

GetFaxListOptions getFaxListOptions = new GetFaxListOptions();
getFaxListOptions.setLimit(Optional.of(5));

InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.getFaxList(Optional.of(getFaxListOptions));

More: documentation

Get Completed Fax List

Get details for a subset of completed faxes from a submitted list. (Submitted id's which have not completed are ignored).

InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.getCompletedFaxList(new String[]{"667915751", "667915471"});

More: documentation

Get Outbound Fax Record

Retrieves information regarding a previously-submitted fax, including its current status.

InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure outboundFaxStructure = interFAX.getOutboundFaxRecord("667915751");

More: documentation

Get Outbound Fax Image

Retrieve the fax image (TIFF file) of a submitted fax.

InterFAX interFAX = new DefaultInterFAXClient();
byte[] faxImage = interFAX.getOutboundFaxImage("667915751");

More: documentation

Cancel a Fax

Cancel a fax in progress.

InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.cancelFax("279499862");

More: documentation

Search Fax List

Search for outbound faxes.

InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.searchFaxList();

Using additional Options: ids, reference, dateFrom, dateTo, status, userId, faxNumber, limit, offset

SearchFaxOptions searchFaxOptions = new SearchFaxOptions();
searchFaxOptions.setLimit(Optional.of(3));
searchFaxOptions.setFaxNumber(Optional.of("+442084978672"));
InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.searchFaxList(Optional.of(searchFaxOptions));

More: documentation

Hide Fax

Hide a fax from listing in queries (there is no way to unhide a fax).

InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.hideFax("667915469");

More: documentation

Inbound

Get list | Get record | Get image | Get emails | Mark as read | Resend to email

Get Inbound Fax List

Retrieves a user's list of inbound faxes. (Sort order is always in descending ID).

InterFAX interFAX = new DefaultInterFAXClient();
InboundFaxStructure[] inboundFaxStructures = interFAX.getInboundFaxList();

Using additional Options: unreadOnly, limit, lastId, allUsers

GetInboundFaxListOptions getInboundFaxListOptions = new GetInboundFaxListOptions();
getInboundFaxListOptions.setAllUsers(Optional.of(true));
getInboundFaxListOptions.setUnreadOnly(Optional.of(true));
getInboundFaxListOptions.setLimit(Optional.of(3));
InterFAX interFAX = new DefaultInterFAXClient();
InboundFaxStructure[] inboundFaxStructures = interFAX.getInboundFaxList(Optional.of(getInboundFaxListOptions));

More: documentation

Get Inbound Fax Record

Retrieves a single fax's metadata (receive time, sender number, etc.).

InterFAX interFAX = new DefaultInterFAXClient();
InboundFaxStructure inboundFaxStructure = interFAX.getInboundFaxRecord("292626603");

More: documentation

Get Inbound Fax Image

Retrieves a single fax's image.

InterFAX interFAX = new DefaultInterFAXClient();
byte[] faxImage = interFAX.getInboundFaxImage(292626603);

More: documentation

Get Forwarding Emails

Retrieve the list of email addresses to which a fax was forwarded.

InterFAX interFAX = new DefaultInterFAXClient();
InboundFaxesEmailsStructure inboundFaxesEmailsStructure = interFAX.getInboundFaxForwardingEmails("1234567");

More: documentation

Mark As Read/Unread

Mark a transaction as read/unread.

InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.markInboundFax("292626603", Optional.of(true));

More: documentation

Resend Inbound Fax

Resend an inbound fax to a specific email address.

InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.resendInboundFax("292626603", Optional.of("someone@example.com"));

More: documentation

Documents

Upload Document | Get list | Status | Get Upload Status | Cancel

Document uploads are useful for several situations:

Upload Document

Upload a large file in 1 MB chunks

String absoluteFilePath = this.getClass().getClassLoader().getResource("A17_FlightPlan.pdf").getFile();
File file = new File(absoluteFilePath);

InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.uploadDocument(file);

With additional options,

String absoluteFilePath = this.getClass().getClassLoader().getResource("A17_FlightPlan.pdf").getFile();
File file = new File(absoluteFilePath);

InterFAX interFAX = new DefaultInterFAXClient();
DocumentUploadSessionOptions documentUploadSessionOptions = new DocumentUploadSessionOptions();
documentUploadSessionOptions.setName(Optional.of("overriddenname.pdf"));
documentUploadSessionOptions.setSize(Optional.of(Integer.toUnsignedLong(12345)));
documentUploadSessionOptions.setDisposition(Optional.of(Disposition.multiUse));
documentUploadSessionOptions.setSharing(Optional.of(Sharing.privateDoc));
APIResponse apiResponse = interFAX.uploadDocument(file, Optional.of(documentUploadSessionOptions));

More: documentation - 1, 2

Get Document List

Get a list of previous document uploads which are currently available.

InterFAX interFAX = new DefaultInterFAXClient();
UploadedDocumentStatus[] uploadedDocumentStatuses = interFAX.getUploadedDocumentsList();

With additional Options: limit, offset

InterFAX interFAX = new DefaultInterFAXClient();
GetUploadedDocumentsListOptions getUploadedDocumentsListOptions = new GetUploadedDocumentsListOptions();
getUploadedDocumentsListOptions.setLimit(Optional.of(5));
getUploadedDocumentsListOptions.setOffset(Optional.of(1));
UploadedDocumentStatus[] uploadedDocumentStatuses = interFAX.getUploadedDocumentsList(Optional.of(getUploadedDocumentsListOptions));

More: documentation

Get Upload Status

Get the current status of a specific document upload.

InterFAX interFAX = new DefaultInterFAXClient();
UploadedDocumentStatus uploadedDocumentStatus = interFAX.getUploadedDocumentStatus("deca890355b44b42944970d9773962b5");

More: documentation

Cancel Document

Cancel a document upload and tear down the upload session, or delete a previous upload.

InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.cancelDocumentUploadSession("deca890355b44b42944970d9773962b5");

More: documentation

Contributing

  1. Fork the repo on GitHub
  2. Clone the project to your own machine
  3. Commit changes to your own branch
  4. Test the changes you have made
  5. Push your work back up to your fork
  6. Submit a Pull request so that we can review your changes

Testing

Before submitting a contribution please ensure all tests pass.

The project is setup using maven and tests can be run using the following command:

$ mvn clean test

Releasing

Versioning

The project uses semver for versioning.

Minor Releases

If a change is backwards compatible, it can be committed and pushed straight to master. Versioning is handled automatically by incrementing the minor version by 1 and released automatically by travisCI, using the release script.

Major Releases

For breaking changes / major releases, the version number needs to be manually updated in the project pom. Simply increment the major version by 1 and drop the minor version to 0. Example, if the version in the project pom is as follows:

<version>0.34-SNAPSHOT</version>

A major change should update it to:

<version>1.0-SNAPSHOT</version>

Once updated, committed and pushed to master, travisCI handles releasing the version to maven central.

License

This library is released under the MIT License.