Introduction

Need to create PDF and HTML documents in your software?

Tired of endless output customization request from your users?

Looking for an easy and fast solution to your problems?

With Actual Reports platform your users can easily create and manage different document templates with an easy-to-use browser based document editor. And, you can use simple RESTful API calls to merge the templates with data from your own software to generate PDF and HTML documents. Or just use Actual Reports platform as an internal tool to manage and generate different outputs needed within your software. This way you don’t have to waste your time or your developers’ time on hard-coding the output layouts.

Benefits

  1. Don’t worry about the document generation layer in your software we will handle it.
  2. Spare your server from overload – document generation can drastically increase your server load.
  3. Spend time on more important tasks by minimizing the hours spent on creating custom outputs for your users.
  4. Create good-looking PDF and HTML documents within seconds.

How Actual Reports has helped other developers?

Margn

Online accounting software Margn uses Actual Reports as an internal tool to create and manage all their reports, invoices, and other necessary documents. According to Margn’s CEO Taavi Hõbejõgi, Actual Reports helps them to save almost 50 working hours when creating over 60 different outputs they need in their software.

Erply

Erply is a cloud based ERP that uses Actual Reports to allow its users to customize invoices, quotes, labels and other documents. Erply’s users have already created over 2000 different templates, which vary from simple bar-code labels to customized weekly sales reports.

Getting Started

The first thing you need is a developer account, that you can create here. The next step is getting your public and private keys, which are located under "Account settings" (After login click on the e-mail on the top right). Now start reading the documentation and check out the available client libraries. We wish you good luck on building something cool! If you need any help then contact our support.



Create your FREE developer account



Actual Reports Account Settings Actual Reports Account Settings

Workflow Schema

Schema

Pricing

The Sandbox developer account is free for developing and testing the integration.
For production environment pricing information please contact info@actualreports.com for details.

Authentication

With every request you always have to specify following parameters

  1. apikey - your public key to identify your account
  2. email - unique email to identify which user is accessing the platform
  3. timestamp - current time measured in the number of seconds since the Unix Epoch
  4. signature - unique hash for every request to ensure that the query is valid.

Creating signature

First you need to create a signature string that is made up from following values:

  • 1. $privateKey - your private key
  • 2. $apiKey - your public key
  • 3. $resource - resource string without the slashes and in lowercase e.g “editor”, “template”, “template123output”
  • 4. $email - user email
  • 5. $timestamp - same timestamp specified in previous section

Second step is to hash the combined string using SHA-256 function to get the signature.

Signature creation pseudocode example

We want to retrieve user templates using: https://app.actualreports.com/api/v2/template

            $privateKey = '68db1902ad1bb26d34b3f597488b9b28';
            $apiKey = '61e5f04ca1794253ed17e6bb986c1702';
            $resource = 'template';
            $email = 'demo@actualreports.com';
            $timestamp = '1380274480';

            $string =  $privateKey + $apiKey + $resource + $email + $timestamp; // Must be in this order
            $signature = hash(SHA-256, $string);

            $url = 'https://app.actualreports.com/api/v2/template?apikey=' + $apiKey + '&email=' + $email + '&timestamp=' + $timestamp + '&signature=' + $signature';
          

Finzalised url

https://app.actualreports.com/api/v2/template?apikey=61e5f04ca1794253ed17e6bb986c1702&email=demo@actualreports.com&timestamp=1380274480&signature=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

NB! It is very important to combine the parameters in correct order.
NB! Signature is valid for 1 minute after creation to protect you against url hijacking and reusing same url over and over again.
NB! Your authentication parameters and method request parameters must be urlencoded and formatted as a valid URL querystring segment.
NB! When you are using one of our helper libraries all this is handled for you.

Error Codes

Errors are returned using HTTP error code syntax. All additional info about the error is sent JSON-formatted in response body.

Code Description
401 Authentication failed
401 Required parameter missing
403 Access not granted
404 Entity not found
404 Resource not found
422 Incorrect parameter value
500 Internal error

Example error response

            {
              "error": "Authentication failed: request expired",
              "status": 401
            }

/editor

POST || GET https://app.actualreports.com/api/v2/editor

Redirecting your users to this url allows them to create and edit their templates. You can also display it inside the iframe. We reccomend you to always send the data parameter to give your user context, and preview ability when creating the template

Input parameters

Name Type Required Values Default Description
templateintegeroptional
dataformatstringoptionaljson
csv Semicolon separated
csv; Semicolon separated
csv, Comma separated
xls Microsoft Excel 2007 and older
xlsx Microsoft Excel
jsonData format
datastringoptionalA list of items given as string or url in supported dataformat
iframeintegeroptional0 Use regular editor design
1 Use minified editor design
0Switch between minified and regular editor design

/template

GET https://app.actualreports.com/api/v2/template

Returns list of templates availbale for the user.

Input parameters

Name Type Required Values Default Description
accessstringoptionalpublic Return public templates
organization Return organization templates
private Return private templates
Comma separated list: public, organization, privateFilter templates by access rights
breakcacheintegeroptional0 Returns response from cahce
1 Force to refresh the response
0Use this parameter to clear cache.

Output fields

Name Type Description
idinteger
namestring
ownerbooleanIndicates whether the user is the owner of the template
modifiedstringTimestamp when template was last modified
tagsarrayList for user assigned tags

Output example

{
  "response": [
    {
      "id": 14817,
      "name": "Packing slip",
      "modified": "2013-09-23 09:10:27",
      "owner": false,
      "tags": [
        "packing"
      ]
    },
    {
      "id": 14815,
      "name": "Invoice",
      "modified": "2013-09-23 09:10:16",
      "owner": false,
      "tags": [
        "invoice"
      ]
    },
    {
      "id": 14830,
      "name": "Product Shelf Label (for label printer)",
      "modified": "2013-09-23 09:10:08",
      "owner": false,
      "tags": [
        "labels"
      ]
    },
    {
      "id": 14831,
      "name": "Address and Mailing label",
      "modified": "2013-09-23 09:09:27",
      "owner": false,
      "tags": [
        "mailing labels"
      ]
    }
  ],
  "meta": [
    
  ]
}

/template/#{id}/output

POST https://app.actualreports.com/api/v2/template/#{id}/output

Merges data with the template and returns output in specified format. You can aquire #{id} using the /template request.

Input parameters

Name Type Required Values Default Description
formatstringoptionalpdf
html
pdf
outputstringoptionalS Returns output as string
I Shows output inline (e.g in browser)
D Starts automatic download
base64 Returns file in base64 encoding
DS returns output in response body. Values I and D expect you to redirect user to URL. base64 returns usual json response.
printintegeroptional0
1
0Set value 1 to automatically open print dialog when file is opened or loaded in browser
dataformatstringoptionaljson
csv Semicolon separated
csv; Semicolon separated
csv, Comma separated
xls Microsoft Excel 2007 and older
xlsx Microsoft Excel
jsonData format
datastringoptionalA list of items given as string or url in supported dataformat

Output example

Output when parameter output value is base64
{
  "response": "JVBERi0xLjcKJeLjz9MKNiAwIG9iago8....",
  "meta": {
    "encoding": "base64",
    "content-type": "application\/pdf"
  }
}