}

/v1/document/merge/

https://api.reporting.cloud/v1/document/merge

Merges and returns a compatible template from the template storage or an uploaded template with hierarchical JSON data.

Document Quota

This method counts against the document quota. For each successful request, the quota count is increased by 1.

Authorization

This endpoint requires a "ReportingCloud-APIKey" or a "Basic" user authorization to access the user acount, data and templates. Only one of these two methods are required.

ReportingCloud-APIKey
Header field Description
Authorization

Required. A valid ReportingCloud account is required. The Authorization field is constructed as follows:

An API Key needs to be generated using the portal or /v1/account/apikey endpoint. The authorization method and a space i.e. "ReportingCloud-APIKey " is then put before the actual API Key string.

Sample:

Authorization: ReportingCloud-APIKey oMDM4MrAqL9QEOpyzupnQW5NjvCNtvE5cVDaaLqxI
Basic
Header field Description
Authorization

Required. A valid ReportingCloud account is required. The Authorization field is constructed as follows:

The username and password are combined into a string separated by a colon, e.g.: username:password. The resulting string is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line. The authorization method and a space i.e. "Basic " is then put before the encoded string.

Sample:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Request Parameters

Query Parameter Value Type Description
returnFormat String A string that specifies the format of the created document. Possible values are: PDF, PDFA, RTF, DOC, DOCX, HTML and TX.
templateName String Optional. The name of the template in the template storage. If no template is specified, the template must be uploaded in the MergeBody object of this request.
append Boolean Optional. Specifies whether the documents should be appened to one resulting document when more than 1 data row is passed.
test Boolean Optional. Specifies whether it is a test run or not. A test run is not counted against the quota and created documents contain a watermark. Not possible using the Free or Trial license.

Request Payload

Value Type Description
MergeBody The MergeBody object contains the datasource as a JSON data object and optionally, a template encoded as a Base64 string and a ReportingCloud MergeSettings object.

MergeBody

Key Value Type Description
mergeData JSON object The datasource for the merge process as a JSON array.
template Base64 encoded string Optional. The template encoded as a Base64 string. Supported formats are RTF, DOC, DOCX and TX.
mergeSettings ReportingCloud MergeSettings object Optional. Optional merge settings to specify merge properties and document properties such as title and author.

MergeSettings

Key Value Type Description
removeEmptyFields Boolean Optional. Specifies whether empty fields should be removed from the template or not. The default value is true.
removeEmptyBlocks Boolean Optional. Specifies whether the content of empty merge blocks should be removed from the template or not. The default value is true.
removeEmptyImages Boolean Optional. Specifies whether images which don't have merge data should be removed from the template or not. The default value is false.
removeEmptyLines Boolean Optional. Specifies whether lines should be removed that contain only empty fields and no other content. The default value is false.
removeTrailingWhitespace Boolean Optional. Specifies whether trailing whitespace should be removed before saving a document. The default value is true.
mergeHtml Boolean Optional. Specifies whether field data can contain formatted Html content or not. The default value is false. Html content must be enclosed in an tag element. Only active in the Merge endpoint.
author String Optional. Sets the document's author.
creationDate DateTime (String) Optional. Sets the document's creation date which will be saved in the document.
lastModificationDate DateTime (String) Optional. Sets the date the document is last modified.
creatorApplication String Optional. Sets the application, which has created the document.
documentSubject String Optional. Sets the document's subject string which will be saved in the document. PDF limitation: The length is limited to 2000 characters.
documentTitle String Optional. Sets the document's title that will be saved in the document. PDF limitation: The length is limited to 2000 characters.
userPassword String Optional. Specifies the password for the user to open the document.
culture String Optional. Specifies the culture for the merge process for date and currency values. It must be the Language Culture Name that can be found in this list. For French use "fr-FR", for German "de-DE". Default is English "en-US".

Success Response

Return Value Description

200 (OK)

 On success, the HTTP status code in the response header is 200 (OK). The response body contains an array of the created documents encoded as Base64 encoded strings.

Error Response

Return Value Description

403 (Forbidden)

 A 403 (Forbidden) is returned, if the user is not authorized, the document quota is exceeded or more than 2 concurrent requests came in from the same account.

400 (Bad Request)

 A 400 (Bad Request) is returned, if no data is found in the MergeBody object, no template is uploaded or template is not found in the template storage.
Timeout Limitation

The pure processing time is limited to a maximum of 60 seconds. After this period of time, the task is cancelled.

A typical document should not take more than 5 seconds. If your requests takes longer, please decrease the number of data rows and reduce the template size.

Sample Requests

Request:

curl -u username:password \
-H "Content-Type: application/json" \
--data \
"
{
\"mergeData\": [
{
\"OrderNumber\": \"O2787346623\",
\"Name\": \"JackJohnson\",
\"Articles\": [
{
\"Name\": \"Article1\"
},
{
\"Name\": \"Article2\"
}
]
},
{
\"OrderNumber\": \"O2787346623\",
\"Name\": \"Jack2Johnson2\",
\"Articles\": [
{
\"Name\": \"Article1\"
},
{
\"Name\": \"Article2\"
}
]
}
],
\"template\": null,
\"mergeSettings\": null
}
"
-X POST https://api.reporting.cloud/v1/document/merge?templateName=test_invoice.tx
view raw ReportingCloud.Document.Merge.Curl hosted with ❤ by GitHub

Results:

["JVBERi0xLjQNJeLjz9MNMSAwIG9iago8PAovVH..."]
view raw ReportingCloud.Document.Merge.Curl.Results.json hosted with ❤ by GitHub

Request:

using System;
using System.Collections.Generic;
using System.Drawing;
using System.IO;
using TXTextControl.ReportingCloud;
class RCSamples
{
public static void MergeDocument(string templateName)
{
ReportingCloud rc = new ReportingCloud(
"username",
"password",
new Uri("https://api.reporting.cloud"));
try
{
// create dummy data
Invoice invoice = new Invoice();
invoice.yourcompany_companyname = "Text Control, LLC";
invoice.invoice_no = "Test_R667663";
// create a new MergeBody object
MergeBody body = new MergeBody();
body.MergeData = invoice;
// merge the document
List<byte[]> results = rc.MergeDocument(body, templateName, ReturnFormat.PDF);
foreach (byte[] document in results)
{
string sFilename = Guid.NewGuid().ToString() + ".pdf";
File.WriteAllBytes(sFilename, document);
Console.WriteLine(sFilename + " has been written.");
}
}
catch (Exception e)
{
Console.WriteLine("An error occurred: " + e.Message);
}
}
public class Invoice
{
public string yourcompany_companyname { get; set; }
public string invoice_no { get; set; }
}
}
view raw ReportingCloud.Document.Merge.Dotnet.cs hosted with ❤ by GitHub

Results:

67e86845-9b85-4f67-83b5-49151e23b37b.pdf has been written.
view raw ReportingCloud.Document.Merge.Dotnet.Results hosted with ❤ by GitHub

Request:

import com.textcontrol.reportingcloud.MergeBody;
import com.textcontrol.reportingcloud.MergeSettings;
import com.textcontrol.reportingcloud.ReportingCloud;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;
class NestedItem {
public final int item_no;
public final String item_description;
public final double item_total;
public NestedItem(int item_no, String item_description, double item_total) {
this.item_no = item_no;
this.item_description = item_description;
this.item_total = item_total;
}
}
class MasterItem {
public final ArrayList<NestedItem> item;
public final String recipient_name;
public final String billto_name;
public MasterItem(String recipient_name, String billto_name) {
this.item = new ArrayList<>();
this.recipient_name = recipient_name;
this.billto_name = billto_name;
}
}
public class ReportingCloudSample {
public static void main(String[] args) throws IOException {
// Generate two rows of dummy data:
MasterItem[] mergeData = {
new MasterItem("Will Ferrell", "Colin Farrell"),
new MasterItem("Morgan Freeman", "Martin Freeman")
};
mergeData[0].item.add(new NestedItem(23, "An Item.", 234.56));
mergeData[0].item.add(new NestedItem(34, "Another item.", 345.67));
mergeData[1].item.add(new NestedItem(45, "Yet another item.", 456.78));
mergeData[1].item.add(new NestedItem(56, "And another one.", 567.89));
// Prepare merge settings and merge body objects
MergeSettings mergeSettings = new MergeSettings();
mergeSettings.setAuthor("John Doe");
mergeSettings.setDocumentTitle("A document merged by Text Control ReportingCloud.");
MergeBody mergeBody = new MergeBody(mergeData, mergeSettings);
// Merge the document
ReportingCloud r = new ReportingCloud("username", "password");
List<byte[]> mergeResult = r.mergeDocument(mergeBody, "sample_invoice.tx");
for (int i = 0; i < mergeResult.size(); ++i) {
String fileName = "merge_result_" + String.format("%02d", i) + ".pdf";
Files.write(Paths.get(fileName), mergeResult.get(i));
System.out.println("Merge result written to " + fileName + ".");
}
}
}
view raw reporting_cloud.document.merge.java hosted with ❤ by GitHub

Results:

Merge result written to merge_result_00.pdf.
Merge result written to merge_result_01.pdf.
view raw reporting_cloud.document.merge.java.result hosted with ❤ by GitHub

Request:

#!/usr/bin/env ruby
require "txtextcontrol/reportingcloud"
require "txtextcontrol/reportingcloud/merge_body"
require "txtextcontrol/reportingcloud/merge_settings"
require "base64"
reporting_cloud = TXTextControl::ReportingCloud::ReportingCloud.new("username", "password")
# Create two "rows" of dummy merge data
merge_data = [
{
"billto_name" => "Will Ferrell",
"recipient_name" => "Colin Farrell",
"item" => [
{
"item_no" => 23,
"item_description" => "An Item.",
"item_total" => 234.56
},
{
"item_no" => 34,
"item_description" => "Another Item.",
"item_total" => 345.67
}
]
},
{
"billto_name" => "Morgan Freeman",
"recipient_name" => "Martin Freeman",
"item" => [
{
"item_no" => 45,
"item_description" => "Yet another item.",
"item_total" => 456.78
},
{
"item_no" => 56,
"item_description" => "And another one.",
"item_total" => 567.89
}
]
}
]
merge_settings = TXTextControl::ReportingCloud::MergeSettings.new
merge_settings.document_title = "Merged document."
merge_settings.author = "John Doe"
merge_body = TXTextControl::ReportingCloud::MergeBody.new(merge_data, merge_settings)
merge_results = reporting_cloud.merge_document(merge_body, "sample_invoice.tx")
i = 0
while i < merge_results.length do
file_name = "merge_result_#{i.to_s.rjust(2, "0")}.pdf"
File.open(File.dirname(__FILE__) + "/#{file_name}", 'wb') do |f|
f.write(Base64.strict_decode64(merge_results[i]))
end
puts "Merge result written to #{file_name}."
i += 1
end
view raw reporting_cloud.document.merge.rb hosted with ❤ by GitHub

Results:

Merge result written to merge_result_00.pdf.
Merge result written to merge_result_01.pdf.
view raw reporting_cloud.document.merge.rb.result hosted with ❤ by GitHub

Request:

<?php
use TxTextControl\ReportingCloud\ReportingCloud;
$reportingCloud = new ReportingCloud([
'api_key' => Helper::apiKey(),
]);
$mergeData = [
0 => [
'yourcompany_companyname' => 'Text Control, LLC',
'yourcompany_zip' => '28226',
'yourcompany_city' => 'Charlotte',
'yourcompany_street' => '6926 Shannon Willow Rd, Suite 400',
'yourcompany_phone' => '704 544 7445',
'yourcompany_fax' => '704-542-0936',
'yourcompany_url' => 'www.textcontrol.com',
'yourcompany_email' => 'sales@textcontrol.com',
'invoice_no' => '778723',
'billto_name' => 'Joey Montana',
'billto_companyname' => 'Montana, LLC',
'billto_customerid' => '123',
'billto_zip' => '27878',
'billto_city' => 'Charlotte',
'billto_street' => '1 Washington Dr',
'billto_phone' => '887 267 3356',
'payment_due' => '20/1/2016',
'payment_terms' => 'NET 30',
'salesperson_name' => 'Mark Frontier',
'delivery_date' => '20/1/2016',
'delivery_method' => 'Ground',
'delivery_method_terms' => 'NET 30',
'recipient_name' => 'Joey Montana',
'recipient_companyname' => 'Montana, LLC',
'recipient_zip' => '27878',
'recipient_city' => 'Charlotte',
'recipient_street' => '1 Washington Dr',
'recipient_phone' => '887 267 3356',
'item' => [
0 => [
'qty' => '1',
'item_no' => '1',
'item_description' => 'Item description 1',
'item_unitprice' => '2663',
'item_discount' => '20',
'item_total' => '2130.40',
],
1 => [
'qty' => '1',
'item_no' => '2',
'item_description' => 'Item description 2',
'item_unitprice' => '5543',
'item_discount' => '0',
'item_total' => '5543',
],
],
'total_discount' => '532.60',
'total_sub' => '7673.4',
'total_tax' => '537.138',
'total' => '8210.538',
],
];
// copy data 4 times
// total record sets = 5
for ($i = 0; $i < 5; $i++) {
array_push($mergeData, $mergeData[0]);
}
$mergeSettings = [
'creation_date' => time(),
'last_modification_date' => time(),
'remove_empty_blocks' => true,
'remove_empty_fields' => true,
'remove_empty_images' => true,
'remove_trailing_whitespace' => true,
'author' => 'James Henry Trotter',
'creator_application' => 'The Giant Peach',
'document_subject' => 'The Old Green Grasshopper',
'document_title' => 'James and the Giant Peach',
'user_password' => '123456789',
];
$templateName = 'test_template.tx';
$arrayOfBinaryData = $reportingCloud->mergeDocument($mergeData, 'PDF', $templateName, null, false, $mergeSettings);
foreach ($arrayOfBinaryData as $index => $binaryData) {
$destinationFile = sprintf('test_document_%d.pdf', $index);
$destinationFilename = sys_get_temp_dir() . DIRECTORY_SEPARATOR . $destinationFile;
file_put_contents($destinationFilename, $binaryData);
var_dump("Merged {$templateName} was written to {$destinationFilename}");
}
view raw ReportingCloud.Document.Merge.Php hosted with ❤ by GitHub

Results:

string(63) "Merged test_template.tx was written to /tmp/test_document_0.pdf"
string(63) "Merged test_template.tx was written to /tmp/test_document_1.pdf"
string(63) "Merged test_template.tx was written to /tmp/test_document_2.pdf"
string(63) "Merged test_template.tx was written to /tmp/test_document_3.pdf"
string(63) "Merged test_template.tx was written to /tmp/test_document_4.pdf"
view raw ReportingCloud.Document.Merge.Php.Result hosted with ❤ by GitHub

Post