Documentation

DXCloud API REST Documentation

General considerations

DXCloud is a REST service that allows for the remote generation of Documents out of an ODT template (that can be edited with Word, LibreOffice, OpenOffice, …) and some provided data in JSON format.

The only requirement is:

  • A free DXCloud account. You may get on in here if you don't have one yet.

There are three main methods available that will be explained in what follows:

  • generateAccessToken: this method returns an access token needed for any further request to the API. This token expires after an hour.
  • generateDocument: this method returns a base64 encoded document in the requested format (.pdf, .docx, .doc, .odt or .rtf) out of a base64 encoded template (in .odt format) and the provided data.
  • convertDocument: this method returns a base64 encoded document in the requested output format (see below for available conversions types).

API endpoint

The endpoint for all API requests is: https://api.docxpresso.cloud/

The URLs for the different available methods are:

  • generateAccessToken [GET]: https://api.docxpresso.cloud/generateAccessToken
  • generateDocument [POST]: https://api.docxpresso.cloud/generateDocument
  • convertDocument [POST]: https://api.docxpresso.cloud/convertDocument

GET generateAccessToken

Request

This method uses Api Key Authorization.

This requires to include a X-Api-Key header in the request including the api key provided in your user dashboard:

X-Api-Key: dGVz...

Response

If the provided data corresponds to the one of a registered user the service will respond with an HTTP status code of 200 and a JSON with the following structure:

{
	"accessToken": "fb567......",
	"currentTime": 1576149311,
	"expires": 1576152911,
	"remainingQuota": {
		"hour": 978,
		"month": 8675,
		"transfer": "976MB"},
	"usage": {
		"month": 22,
		"total": 2645}
}

Otherwise there will be a 403 HTTP status code returned and content:

{"error":"Authorization incorrect."}

In the case of a positive answer you should store the provided accessToken because it will be required in all subsequent requests to the API.

All other data is purely informative:

  • currentTime: is the UNIX time of the API endpoint server.
  • expires: is expiration time of the access token given as the UNIX time of the API endpoint server (1 hour after request).
  • remainingQuota: give you info about the remaining API quotas for the free API usage. Notice that independent throttling (no more that 2 requests per second to the API) limitations may also apply.
  • usage: info about the documents generated in the current month and in total (you may get more detailed info in your user dashboard).

POST generateDocument

Request

In order to gain API access you need to provide an Authorization header with the access token provided by the generateAccessToken method:

Authorization: Bearer fb567.....

This method requires that you send by RAW POST, i.e. in the request body, a JSON encoded object with the general structure:

{
    "template":"base64 encoded odt file",
    "output": "odt|pdf|doc|docx|rtf",
    "replace": [
        {
            "vars": [
                {
                 "var": "variable name",
                 "value": ["first", "second", "third"],
                 "html": true,
                 "parse-line-breaks": false,
                 "block-type": false,
                 "image": false,
                 "match": 1,
                 "width": "200px",
                 "height": "150px"
                },
                {
                 "var": "other variable name",
                 "value": ["first value", "second value", "third value"],
                 "html": true,
                 "parse-line-breaks": false,
                 "block-type": false,
                 "image": false,
                 "match": 1,
                 "width": "200px",
                 "height": "150px"   
                }
            ],
            "options": {
                "element": "text|paragraph|list|table|image",
                "target": "document|header|footer",
                "html": true,
                "parse-line-breaks": false,
                "block-type": false,
                "image": false,
                "match": 1
            }
        }
    ],
    "remove": [
        {
            "options": {
                "needle": "variable name",
                "element": "text|bookmark|paragraph|list|list-item|table|table-row|image|chart|textbox|heading",
                "target": "document|header|footer",
                "heading-level": 1,
                "match": 1,
                "container": false
            }
        }
    ],
    "clone": [
        {
            "options": {
                "needle": "variable name",
                "element": "bookmark|paragraph|list|list-item|table|table-row|image|chart|textbox|heading",
                "repeat": 1,
                "target": "document|header|footer",
                "heading-level": 1,
                "match": 1,
                "container": false
            }
        }
    ],
    "charts": [
        {
            "var": "chart name",
            "data": "json encoded chart data as defined in the replaceChartdata method",
            "match": 1
        }
    ]
}

The JSON structure can be divided into blocks:

{
    "template":"",
    "output": "",
    "replace": [ ],
    "remove": [ ],
    "clone": [ ],
    "charts": [ ]
}

template

This property is always required. Its value must be a document in odt format (Open Document Text) base64 encoded.

The provided odt file should contain the required Docxpresso variables wrapped in double curly brackets: {{variableName}}

output

This property is optional and it defaults to odt if not given.

It determines the format of the returned document. The accepted values are pdf, docx, odt, doc or rtf.

replace

This property is optional.

It is an array with all the required info to replace Docxpresso variables by their desired value.

Each array element should be a json encoded object with the following general structure:

{
    "vars": [
        {
         "var": "variable name",
         "value": ["first", "second", "third"],
         "html": true,
         "parse-line-breaks": false,
         "block-type": false,
         "image": false,
         "match": 1,
         "width": "200px",
         "height": "150px"
        },
        {
         "var": "other variable name",
         "value": ["first value", "second value", "third value"],
         "html": true,
         "parse-line-breaks": false,
         "block-type": false,
         "image": false,
         "match": 1,
         "width": "200px",
         "height": "150px"   
        }
    ],
    "options": {
        "element": "text|paragraph|list|table|image",
        "target": "document|header|footer",
        "html": true,
        "parse-line-breaks": false,
        "block-type": false,
        "image": false,
        "match": 1
    }
}

The variables of each of this array elements are:

vars

This property is required within the replace object.

An array of objects each of one containing info about a particular Docxpresso variable to be replaced. Each of these objects contain the following properties:

var

This property is required within the vars object.

The name (without curly brackets) of the Docxpresso variable to be replaced. If the variable name does not exist within the template this replacement will be simply ignored.

value

This property is required within the vars object.

The array of values used for replacement. If the number of provided values is smaller than the number of appearances of that variable in the template Docxpresso will cycle over the array. For example, if only one value is provided that value will be used for all replacements.

html

This property is optional with default value true.

If true the values provided may contain HTML that will be parsed before replacement. If block-type is set to false (default value) only "inline HTML" will be parsed.

parse-line-breaks

This property is optional with default value false.

If html is set to false we may request Docxpresso to parse line breaks within the values.

block-type

This property is optional with default value false.

If set to true the paragraph containing the variable will be removed and replace by the value provided. Notice that if html is set to true the value may contain tables, paragraphs, headings, etc in HTML format that will be rendered within the document.

image

This property is optional with default value false.

If set to true Docxpresso will look for images with alt text equal to the variable name (something of the type {{imageName}}).

The provided values may be a URL with the image or a string or a dati URI scheme: https://en.wikipedia.org/wiki/Data_URI_scheme or in simple words something of the type: data:image/png;base64,iVBORw0K….

match

This property is optional.

The order of appearance of the variable in the set of matches in the document. For example, if set to 1 only the first appearance will be replaced. If not given all matches will be replaced.

width

This property is optional.

It only applies to images and sets the desired width of the image in px, pt, in, cm, …

If not given the template dimensions will be left unchanged.

height

This property is optional.

It only applies to images and sets the desired height of the image in px, pt, in, cm, …

If not given the template dimensions will be left unchanged.

options

This property is optional.

An object with properties that will apply to all the replacements in case their values are not explicitly provided within each var object:

element

This property is optional with default value text.

If set to a different value the Docxpresso parser will try to clone the provided element as many times as needed to accommodate the provided values, i.e. if the variables all belong to a table and three different values are provided the table will be automatically cloned twice so all three values may be rendered.

Possible values are: text, paragraph, list, table and also image, although in this last case the cloning will not be automatic (this is just to simplify the json structure in case we may need to replace many images in a single template).

target

This property is optional with default value document

Indicates where Docxpresso should look for the variable:

  • document: the body of the document (default value)
  • header: the header of the document
  • footer: the footer of the document

html

This property is optional with default value true.

The global html value for that set of variables. It may be overwritten by each single variable within the vars property.

parse-line-breaks

This property is optional with default value false.

The global parse-line-breaks value for that set of variables. It may be overwritten by each single variable within the vars property.

block-type

This property is optional with default value false.

The global block-type value for that set of variables. It may be overwritten by each single variable within the vars property.

image

This property is optional with default value false.

The global image value for that set of variables. It may be overwritten by each single variable within the vars property.

match

This property is optional.

The global match value for that set of variables. It may be overwritten by each single variable within the vars property. If not given all matches will be replaced.

remove

This property is optional.

This is an array with all the required info to remove blocks of content within a document.

IMPORTANT: this is the first block of instructions to be run independently of its order within the JSON.

Each array element should be a json encoded object with the following general structure:

{
    "options": {
        "needle": "variable name",
        "element": "text|bookmark|paragraph|list|list-item|table|table-row|image|chart|textbox|heading",
        "target": "document|header|footer",
        "heading-level": 1,
        "match": 1,
        "container": false
    }
}

We strongly recommend to use Docxpresso variables as needles. This is so because Word and Libreffice may introduce XML tags that are not visible but may hinder getting the expected result in the search process. Docxpresso variables are parsed to eliminate that issue and you may later delete them or set them to an empty string.

options

This property is required within the remove object.

An object containing the required info to find and remove a block of content:

needle

This property is required but for images and charts.

The needle to be searched in order to identify the block of content to be removed. If no match value is given this parameter is required.

If the element value is chosen to be bookmark the needle should be the name of the desired bookmark.

element

This property is orequired within the options object.

The type of block containing the needle that should be removed.

Possible values are: text, bookmark, paragraph, list, list-item, table, table-row, image, chart, textbox or heading (in this case all content falling within the heading level specified in the property heading-level will be removed).

target

This property is optional and its default value is document.

Where Docxpresso should look for the needle:

  • document: the body of the document (default value)
  • header: the header of the document
  • footer: the footer of the document

heading-level

This property is optional and its default value is 1.

The level of the heading in case the property element is set to heading, otherwise will be ignored if set.

match

This property is optional.

The order of appearance of the block element in the set of matches in the document. For example, if set to 1 only the first appearance will be removed. If not given all matches will be removed.

container

This property is optional and its default value is false.

If the element is image, textbox or chart and container is set to true the container paragraph will be removed.

clone

This property is optional.

This is an array with all the required info to clone blocks of content within a document.

IMPORTANT: this block of instructions will be run after the remove block independently of its order within the JSON.

Each array element should be a json encoded object with the following general structure:

{
    "options": {
        "needle": "variable name",
        "element": "bookmark|paragraph|list|list-item|table|table-row|image|chart|textbox|heading",
        "repeat": 1,
        "target": "document|header|footer",
        "heading-level": 1,
        "match": 1,
        "container": false
    }
}

We strongly recommend to use Docxpresso variables as needles. This is so because Word and Libreffice may introduce XML tags that are not visible but may hinder getting the expected result in the search process. Docxpresso variables are parsed to eliminate that issue and you may later delete them or set them to an empty string.

options

This property is required within the clone object.

An object containing the required info to find and clone a block of content.

needle

This property is optional but for images and charts.

The needle to be searched in order to identify the block of content to be cloned. If no match value is given this parameter is required.

If the element value is chosen to be bookmark the needle should be the name of the desired bookmark.

element

This property is required within the options object.

The type of block containing the needle that should be cloned.

Possible values are: bookmark, paragraph, list, list-item, table, table-row, image, chart, textbox or heading (in this case all content falling within the heading level specified in the property heading-level will be cloned).

repeat

This property is optional and its default value is 1.

The number of times that a given block should be repeated.

target

This property is optional and its default value is document.

Where Docxpresso should look for the needle:

  • document: the body of the document (default value)
  • header: the header of the document
  • footer: the footer of the document

heading-level

This property is optional and its default value is 1.

The level of the heading in case the property element is set to heading, otherwise will be ignored if set.

match

This property is optional and its default value is 1.

The order of appearance of the block element in the set of matches in the document. For example, if set to 2 only the second appearance will be cloned.

container

This property is optional and its default value is false.

If the element is image, textbox or chart and container is set to true the container paragraph will be cloned.

charts

This property is optional.

This is an array with all the required info to modify the data of the required charts within a document.

Each array element should be a json encoded object with the following general structure:

{
   "var": "chart name",
   "data": {},
   "match": 1
}

options

This property is required within the chart object.

An object containing the required info to find and clone a block of content.

var

This property is optional.

The given chart name as alt text. If no match value is given this parameter is required.

data

This property is required within the chart object. You have to provide that data with the same "series and categories" names as in the original chart in the template.

For pie and donought charts the data structure is something like:

"data": {
    "Category 1": 10, 
    "Category 2": 30, 
    "Category 3": 20,
    "Category 4": 6
}

And for all other chart types:

"data": {
    "series": ["Series 1", "Series 2", "Series 3"],
    "Category 1": [10,20, 10], 
    "Category 2": [30,10, 30], 
    "Category 3": [12.5, 50, 5],
    "Category 4": [40, 10, 10]
}

match

This property is optional.

The order of appearance of the chart in the set of matches in the document. For example, if set to 1 only the first appearance will be replaced. If not given all matches will be replaced.

Response

success

If there is no error this method will return a HTTP status code of 200 and the following JSON:

{
    "document":"JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBv….",
    "remainingQuota": {
        "hour": 978,
        "month": 8675,
        "transfer": "976MB"},
    "usage": {
        "month": 22,
        "total": 2645}
}

Where the document property value is the requested document base64 encoded and the remaining properties are just informative about the usage and remaining quotas.

error

The list of possible errors includes:

Status code: 403

{"code": 1, "error":"Authorization incorrect."}

Status code: 400

{"code": 3, "error":"Incorrect JSON format."}
{"code": 5, "error":"Incorrect output format."}
{"code": 6, "error":"Timeout generating the document."}
{"code": 10, "error":"Temporarily out of service. Please, try again later."}
{"code": 11, "error":"Undefined error."}

Status code: 429

{"code": 7, "error":"Too many requests in the last hour."}
{"code": 8, "error":"Too many requests in the current month."}
{"code": 9, "error":"Monthly transfer quota exceeded."}

POST convertDocument

Request

data

This property is required.

This method requires that you send by RAW POST, i.e. in the request body, a JSON encoded object with the general structure:

{
   "input": "input format",
   "output": "output format",
   "source": " base64 encoded file to be converted "
}

input

This property is required.

This property determines the format of the document to be transformed. The accepted values are docx, odt, doc or rtf.

output

This property is required.

This property determines the format of the returned document. The accepted values are pdf, docx, odt, doc or rtf.

source

This property is required.

Its value must be a document to be transformed, in the format provided in the input property, base64 encoded.Response

success

If there is no error this method will return a HTTP status code of 200 and the following JSON:

{
    "document":"JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBv….",
    "remainingQuota": {
        "hour": 978,
        "month": 8675,
        "transfer": 976MB},
    "usage": {
        "month": 22,
        "total": 2645}
}

Where the document property value is the requested document base64 encoded and the remaining properties are just informative about the usage and remaining quotas.

error

The list of possible errors includes:

Status code: 403

{"code": 1, "error":"Authorization incorrect."}

Status code: 400

{"code": 3, "error":"Incorrect JSON format."}
{"code": 5, "error":"Incorrect output format."}
{"code": 6, "error":"Timeout generating the document."}
{"code": 10, "error":"Temporarily out of service. Please, try again later."}
{"code": 11, "error":"Undefined error."}

Status code: 429

{"code": 7, "error":"Too many requests in the last hour."}
{"code": 8, "error":"Too many requests in the current month."}
{"code": 9, "error":"Monthly transfer quota exceeded."}