Free PamFax API

Getting started with the PamFax API

It’s easy to get started with PamFax. API access and usage is easy and FREE. Click “今すぐサインアップ” below and send us a short description on how you plan to use PamFax and we’ll immediately send you your login details to the sandbox API. This environment will provide you with all the documentation and API access so you can start the integration. The sandbox works just like the live, production API. The sandbox will even throw you fax delivery errors randomly so that you can test error handling.

Once you are ready to go live just contact us with a brief explanation of the solutions (and a few screenshots). We will then send you the live production API keys so that you can go live.

You can pay for faxes in two ways. Either you pre-load your PamFax account with enough credit to provide the fax service to your clients as part of your solution or you tell your clients to purchase the required credit themselves. In all cases, the PamFax API will provide you with price and page information so that you can track billing and inform your users of cost.

PamFax API Technical Overview

Application Stack

The PamFax API is made up of the following components:

• PamFax Application Server – The server manages all fax processes and associated data. For now, this means that we host the data in our high availability data center. Part of this environment are the document converter servers which are hosted on a powerful server platform.

• XML API – We’ve designed a highly flexible, standards based XML API which makes integrating with PamFax a snap. The PamFax XML API is an easy way to make programmatic HTTPS requests that result in simple XML responses.

API Features

• Common commands

  Functions related to global information like system status, supported file types, etc.

• Fax History

  Fax history access (inbox, outbox and sent faxes).

• Fax Job

  Functions to create, manage and send a fax.

• Number Information

  Functions about phone numbers like pricing for a particular number, zone rate information, etc.

• Session

  Functions related to session handling, links, login/logout, user verification, etc.

• Commercial

  Functions to handle shop items, vouchers, invoices, pricing information, etc.

• User Info

  Functions to retrieve information about the user, settings, profile, history, etc.

Using the API

You have two possibilities to connect your software to PamFax: either you write the code yourself to communicate with the API via HTTPS XML yourself (see below) or you use one of these libraries:

• PHP client reference implementation;

• C# .NET SDK implementation;

• Java SDK implementation;

• Python library (kudos to Dynaptio);

• Ruby library (kudos to Tropo);

• BASH.

You can view the sample code on the sample page or after logging in to the PamFax API Frontend (free PamFax API account required, sign up below)

Direct API

The PamFax API is a HTTPS GET/POST API that returns XML or JSON response. Arguments are passed using the POST method and must be validated with a checksum that is build on the given arguments. Each call must contain an argument that identifies the caller to ensure security. URL for a call is followed by an API processor and a method name. You may specify how return values shall be encoded using the special argument ‘apioutputformat’. It may be ‘API_FORMAT_XML’ or ‘API_FORMAT_JSON’. In this documentation we’ll show only XML formatted responses because this is API default.

Example call:
URL: Session/VerifyUser/
POST: apikey=yourapikey&apicheck=81c5c66566a60c8805e9739564e5dac5&username=testuser&password=somepass

Result:

                                                        
                                
                                    success
                                
                                
                                
                                
                                    
                                    
                                    
                                    
                                    

                                    
                                    
                                    
                                    
                                
                            
						

In the example resonse you’ll see a tag named ‘UserToken’. This is very important as it must be submitted with many calls to the API to identify the PamFax user the call shall be executed for. For example the FaxJob/Create call needs a validated PamFax user to work.

Securing API calls

All API calls are secured by a checksum-parameter. This ensures that the call is not changed on the way from your application to the PamFax API. You’ll have to calculate this value, so let’s have a look how to do this:

function calculate_api_checksum

1. data := [associative array of values]
2. data := [sort alphabetically by case-insensitive key]
3. checksum := [empty string]
4. for each key/value pair in data
   checksum := [append value]
5. checksum := [append your api secret word]
6. checksum := [calculate md5 of checksum]

Некоторые дополнения:

• [associative array of values] must NOT contain the following arguments: page, event, apikey, apicheck, usertoken.

• [associative array of values] must contain the ‘apioutputformat’ argument if specified.

• [concatenate checksum and value] needs to check if the value is a bool take [true] as 1 and [false] as 0.

• [concatenate checksum and value] needs to loop if value is an array, values keys needs to be converted to lowercase and value must be sorted alphabetically by it’s key (as in 2) and 3) ).

A reference implementation in PHP can be found in apiclient.php in the API client reference implementation (PHP) (see function CalcApiCheck)

Currencies in the API

Internally PamFax operates in Euro. All prices, credit etc. are kept in EUR. The currency values returned by the API are also always in Euro, except when a user is logged in (via Session::VerifyUser) and this user has a different currency set in his profile. Then all currency values are returned in the user’s currency. I.e. NumberInfo::GetPagePrice will return the cost of the fax (field “priceperpage”) in Euro if no user is logged in or if the logged in user has EUR set as his currency. When a user is logged in who has i.e. USD set as his currency, the “priceperpage” will be returned in USD (converted from EUR to USD with the current currency conversion). If you need a list of currency rates PamFax uses, just call Common::ListCurrencies. User’s credit is also returned in user’s currency. The API converts the internally used EUR values to the correct currency for you. This could lead in user’s credit varying from day to day when there are changes in the conversion rate. But as the prices of sending faxes will also be calculated with the same rate, the user always gets exactly the pages he paid for.

Dates in the API

Date/Time values are always returned in standard 24h date format, i.e. FaxHistory::ListInboxFaxes field “received” could look like “2009-04-24 22:44:11″. The time zone of all time fields is calculated based on the user’s settings or a global time zone set for your api account. I.e. we have set your API account to time zone “Asia/Tokyo” (please contact us so that we can set your time zone in your account). Then a fax is created. It will have the “created” field value in time zone value of “Asia/Tokyo”, and not the time of our servers.

Distribute your solution

Commercialize your integration – Are you ready to ship a commercial integration with PamFax? You can do this without any additional cost – using the PamFax API in your solution is FREE. Once you have completed the integration you submit the solution to us for certification. This is free and after successful certification you will be provided with API credentials to access the production API.