Conversion API

Zoho Writer’s conversion API lets you easily integrate document conversion functionality to web applications and content management systems.

The conversion API allows you to convert a file format (say docx) to another file format (say pdf or text).

Apart from supporting popular file formats like .docx .doc .txt .pdf .odt .sxw and .html. Zoho Writer also enable file conversion in its native .zdoc format. 

Purpose 

To convert a document to any Writer supported format (.docx, .doc, .pdf, .zdoc etc.)

HTTP Request URL

https://{api.office-integrator_domain}/writer/officeapi/v1/document/convert

Request Parameters

ParameterData TypeDescription
Mandatory Parameters
apikey423s*****Uniquely identifies the web application which initiates the document conversion request.
document

or

url
File

or

String
Method of providing the input file depending on its location.

document - if the input file is from your local drive or desktop.

url - if the input file is from a publicly accessible Web URL.
output_options{
"format": <String>,
"document_name": <String>,
"password": <String>,
"include_changes":<String>,
"include_comments":<String>
}

format -> Specify the output format in which the converted file needs to be stored.

document_name -> Specify the name for the converted document.

The below key values are optional;

password-> Specify a password if you would like to protect the converted document.

include_changes -> Specify how the track changed content needs to be reflected in converted file. The possible values are:

  • as_markups: If the marked up content needs to included in converted document.
  • all: To generate the converted file by accepting all the track changes done.
  • none: To generate the converted document by rejecting the track changes done.

 

include_comments -> Specify if the comments needs to be included in the converted file or not. The possible values are:

  • all: To generate the converted file with the comments.
  • none: To generate the converted document without the comments.

 

Optional Parameters
passwordStringIf the input document is password protected, specify it using this parameter.

Note:

Users will get a response of the converted document in the form of bytes.

output_options

ParameterTypePossible ValuesDefault Value
Mandatory Parameters 
formatStringdocx / zdoc / doc / odt / html / pdf and more ...docx
document_nameStringNANA
Optional Parameters 
passwordStringNANA
include_changesStringas_markups / all / noneas_markups
include_commentsStringall / noneall

Conversion API - Error Codes

CodeDescription
1831Error occurred. Parameter value is either incorrect or invalid.
1852File format you're trying to import is not supported.
1868Invalid parameter name for uploaded content.

For a full list of error handling cases in Conversion API, refer here.

Sample Request

Copiedcurl -X POST \ 
  'https://api.office-integrator.com/writer/officeapi/v1/document/convert?apikey=423s*****' \
  - H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  - F 'document=@/Users/username/Documents/Sample.docx' \
  - F 'output_options={"format":"docx","document_name":"New"}' 
Copiedconst Levels = require("zoi-nodejs-sdk/routes/logger/logger").Levels;
const Constants = require("zoi-nodejs-sdk/utils/util/constants").Constants;
const APIKey = require("zoi-nodejs-sdk/models/authenticator/apikey").APIKey;
const Environment = require("zoi-nodejs-sdk/routes/dc/environment").Environment;
const LogBuilder = require("zoi-nodejs-sdk/routes/logger/log_builder").LogBuilder;
const UserSignature = require("zoi-nodejs-sdk/routes/user_signature").UserSignature;
const InitializeBuilder = require("zoi-nodejs-sdk/routes/initialize_builder").InitializeBuilder;

const fs = require("fs");
const StreamWrapper = require("zoi-nodejs-sdk/utils/util/stream_wrapper").StreamWrapper;
const FileBodyWrapper = require("zoi-nodejs-sdk/core/com/zoho//officeintegrator/office_integrator_sdk/file_body_wrapper").FileBodyWrapper;
const DocumentConversionParameters = require("zoi-nodejs-sdk/core/com/zoho//officeintegrator/office_integrator_sdk/document_conversion_parameters").DocumentConversionParameters;
const InvaildConfigurationException = require("zoi-nodejs-sdk/core/com/zoho//officeintegrator/office_integrator_sdk/invaild_configuration_exception").InvaildConfigurationException;
const OfficeIntegratorSDKOperations = require("zoi-nodejs-sdk/core/com/zoho//officeintegrator/office_integrator_sdk/office_integrator_sdk_operations").OfficeIntegratorSDKOperations;
const DocumentConversionOutputOptions = require("zoi-nodejs-sdk/core/com/zoho//officeintegrator/office_integrator_sdk/document_conversion_output_options").DocumentConversionOutputOptions;

class ConvertDocument {

    //Include zoi-nodejs-sdk package in your package json and the execute this code.

    static async initializeSdk() {
        let user = new UserSignature("john@zylker.com");
        let environment = new Environment("https://api.office-integrator.com", null, null);
        let apikey = new APIKey("2ae438cf864488657cc9754a27daa480", Constants.PARAMS);
        let logger = new LogBuilder()
            .level(Levels.INFO)
            .filePath("./app.log")
            .build();
        let initialize = await new InitializeBuilder();

        await initialize.user(user).environment(environment).token(apikey).logger(logger).initialize();

        console.log("SDK initialized successfully.");
    }

    static async execute() {
        
        //Initializing SDK once is enough. Calling here since code sample will be tested standalone. 
        //You can place SDK initializer code in your application and call once while your application start-up. 
        await this.initializeSdk();

        try {
            var sdkOperations = new OfficeIntegratorSDKOperations();
            var documentConversionParameters = new DocumentConversionParameters();

            //Either use url as document source or attach the document in request body and use below methods
            documentConversionParameters.setUrl("https://demo.office-integrator.com/zdocs/MS_Word_Document_v0.docx");

            // var fileName = "Graphic-Design-Proposal.docx";
            // var filePath = __dirname + "/sample_documents/Graphic-Design-Proposal.docx";
            // var fileStream = fs.readFileSync(filePath);
            // var streamWrapper = new StreamWrapper(fileName, fileStream, filePath);
            // var streamWrapper = new StreamWrapper(null, null, filePath)

            // documentConversionParameters.setDocument(streamWrapper);

            var outputOptions = new DocumentConversionOutputOptions();

            outputOptions.setFormat("pdf");
            outputOptions.setDocumentName("conversion_output.pdf");
            outputOptions.setIncludeComments("all");
            outputOptions.setIncludeChanges("all");

            documentConversionParameters.setOutputOptions(outputOptions);
            documentConversionParameters.setPassword("***");
            var responseObject = await sdkOperations.convertDocument(documentConversionParameters);

            if(responseObject != null) {
                console.log("\nStatus Code: " + responseObject.statusCode);
    
                //Get the api response object from responseObject
                let writerResponseObject = responseObject.object;

                if(writerResponseObject != null) {
                    if(writerResponseObject instanceof FileBodyWrapper) {
                        var convertedDocument = writerResponseObject.getFile();

                        if (convertedDocument instanceof StreamWrapper) {
                            var outputFilePath = __dirname + "/sample_documents/conversion_output.pdf";

                            fs.writeFileSync(outputFilePath, convertedDocument.getStream());
                            console.log("\nCheck converted output file in file path - ", outputFilePath);
                        }
                    } else if (writerResponseObject instanceof InvaildConfigurationException) {
                        console.log("\nInvalid configuration exception. Exception json - ", writerResponseObject);
                    } else {
                        console.log("\nRequest not completed successfullly");
                    }
                }
            }
        } catch (error) {
            console.log("\nException while running sample code", error);
        }
    }
}

ConvertDocument.execute();

Sample Response

The converted document will be downloaded as bytes.