POST /v1/document/convert
POST https://api.reporting.cloud/v1/document/convert
Description
Converts a document to another format. The request body is the document as a Base64 string: the service recognizes DOCX, DOC, RTF, HTML, PDF, TX and XLSX by their content and reads anything else as plain text. returnFormat names the format to create, PDF by default, and the response is the converted document as a Base64 string. See Converting Documents.
Warning
Document Quota. Each successful request counts 1 against the document quota. A test run (
test=true) doesn't count. Plans and Licensing lists the quota of each plan.
Examples
Request:
curl username:password \
"Content-Type: application/json" \
\
" \
\"CAcBAA4AAAAAAAAAAAAAAAIAAABsAQAAAQ...==\"" \
POST "https://api.reporting.cloud/v1/document/convert?returnFormat=RTF"
Results:
"e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcdWMxXGRlZmYwXGFkZWZmMFxkZWZsYW5n..."
Request:
using System;
using System.Collections.Generic;
using System.Drawing;
using System.IO;
using TXTextControl.ReportingCloud;
class RCSamples
{
public static void ConvertDocument(string templateName)
{
ReportingCloud rc = new ReportingCloud(
"username",
"password",
new Uri("https://api.reporting.cloud"));
try
{
// Read the document and convert it to DOCX
byte[] bDocument = File.ReadAllBytes(templateName);
byte[] bResults = rc.ConvertDocument(bDocument, ReturnFormat.DOCX);
File.WriteAllBytes("results.docx", bResults);
Console.WriteLine(templateName + " has been converted to DOCX.");
}
catch (Exception e)
{
Console.WriteLine("An error occurred: " + e.Message);
}
}
}
Results:
test.tx has been converted to DOCX.
Request:
import com.textcontrol.reportingcloud.ReportingCloud;
import com.textcontrol.reportingcloud.ReturnFormat;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
public class ReportingCloudSample {
public static void main(String[] args) throws IOException {
byte[] documentData = Files.readAllBytes(Paths.get("template.tx"));
ReportingCloud r = new ReportingCloud("username", "password");
byte[] pdfData = r.convertDocument(documentData, ReturnFormat.PDF);
String pdfFileName = "converted.pdf";
Files.write(Paths.get(pdfFileName), pdfData);
System.out.println("Converted document written to " + pdfFileName + ".");
}
}
Results:
Converted document written to converted.pdf.
Request:
#!/usr/bin/env ruby
require "txtextcontrol/reportingcloud"
require "base64"
reporting_cloud = TXTextControl::ReportingCloud::ReportingCloud.new("username", "password")
template_data = File.open(File.dirname(__FILE__) + "/sample_invoice.tx", "rb") { |f| f.read }
template_data_b64 = Base64.strict_encode64(template_data)
convert_result = reporting_cloud.convert_document(template_data_b64)
pdf_file_name = "converted.pdf"
File.open(File.dirname(__FILE__) + "/#{pdf_file_name}", 'wb') do |f|
f.write(Base64.strict_decode64(convert_result))
end
puts "Converted document written to #{pdf_file_name}."
Results:
Converted document written to converted.pdf.
Request:
require_once __DIR__ . '/vendor/autoload.php';
use TextControl\ReportingCloud\ReportingCloud;
$reportingCloud = new ReportingCloud([
'api_key' => (string) getenv('REPORTINGCLOUD_API_KEY'),
]);
$sourceFilename = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'sample_invoice.tx';
$destinationFilename = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'sample_invoice.pdf';
$binaryData = $reportingCloud->convertDocument($sourceFilename, 'PDF');
file_put_contents($destinationFilename, $binaryData);
var_dump("Written converted document to {$destinationFilename}");
Results:
string(53) "Written converted document to /tmp/sample_invoice.pdf"
Authorization
This endpoint requires a "ReportingCloud-APIKey" or a "Basic" user authorization to access the user account, data and templates. Only one of these two methods is required.
API Keys describes how to create an API key, and Authentication explains both header forms.
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 in the portal or with PUT /v1/account/apikey. The authorization method and a space, "ReportingCloud-APIKey ", is then put before the actual API key string. For example: Authorization: ReportingCloud-APIKey oMDM4MrAqL9QEOpyzupnQW5NjvCNtvE5cVDaaLqxI |
Basic
| Header field | Description |
|---|---|
| Authorization | Required. A valid ReportingCloud account is required. The Authorization field is constructed as follows: The user name and password are combined into a string separated by a colon, for example 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, "Basic ", is then put before the encoded string. For example: Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l |
Request Parameters
| Name | Type | Value | Optional |
|---|---|---|---|
| returnFormat | String | A string that specifies the format of the created document. Possible values are: PDF, PDFA, RTF, DOC, DOCX, HTML, TXT and TX, in any letter case. The default value is PDF. PDFA requires an Extreme license. | yes |
| test | Boolean | Specifies whether it is a test run or not. A test run is not counted against the quota, and the created document contains a "TEST MODE" watermark. A PDF gets the title "ReportingCloud Test Mode". Not possible using the Free license. The default value is false. | yes |
Request Payload
| Type | Value |
|---|---|
| Base64 encoded string | The source document encoded as a Base64 string, sent as a JSON string. Possible document formats are .rtf, .doc, .docx, .html, .pdf, .tx, .xlsx and plain text. Data in another format is read as plain text. |
Success Response
| Status | Description |
|---|---|
| 200 | On success, the HTTP status code in the response header is 200 (OK). The response body contains the converted document encoded as a Base64 encoded string. |
Error Response
| Status | Description |
|---|---|
| 400 | A 400 (Bad Request) is returned, if no data is found in the request body, the body is not a JSON string or returnFormat is not one of the possible values. |
| 403 | A 403 (Forbidden) is returned, if the user is not authorized, the document quota is exceeded or the return format PDFA is requested without an Extreme license. |
| 405 | A 405 (Method Not Allowed) is returned, if the request uses another HTTP method than POST. The Allow header of the response names POST. |
| 411 | A 411 (Length Required) is returned, if the request has neither a body nor a Content-Length header. |
| 415 | A 415 (Unsupported Media Type) is returned, if the request has a body but no Content-Type header, or a Content-Type such as text/plain that the endpoint doesn't read. Send Content-Type: application/json. |
| 500 | A 500 (Internal Server Error) is returned, if the request has no Authorization header, an empty one or one that is not the authorization method, a space and the credentials, or if the request body is not a valid Base64 string or returnFormat is empty. |
Timeout Limitation. The pure processing time is limited to a maximum of 60 seconds. After this period of time, the task is canceled.
A typical document should not take more than 5 seconds. If your request takes longer, reduce the size of the document.