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:
There are three main methods available that will be explained in what follows:
The endpoint for all API requests is: https://api.docxpresso.cloud/
The URLs for the different available methods are:
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...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:
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:
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:
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:
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.
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.
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."}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
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.
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."}