Home  »   Zoho API Developers Guide »  Remote API Reference »  Open Document

Open Document

Tags:  

Document Open / Edit

In order to invoke the remote API and open a document in Zoho Service editors, the developer needs to submit a request by way of a HTTPS POST form to the specific Zoho Service url. Depending on the file type (doc, xls, ppt), the request can be sent to the following urls :
  • Zoho Writer - https://exportwriter.zoho.com/remotedoc.im
  • Zoho Sheet - https://sheet.zoho.com/remotedoc.im
  • Zoho Show - https://show.zoho.com/remotedoc.im
Now, there can be a couple of ways of uploading the document to Zoho Service editors via an HTTPS POST form. Depending on the location of the file - desktop or web - developers can use either of the two methods: 
  1. Open a private document - Multi-part form submit - This is used for opening documents present in your computer's local drive or desktop
  2. Open a public document - Normal form submit - This is for opening documents that are present over a web url and accessible by Zoho Document Servers.
Form Request Parameters Reference

Common Parameters

The following are the common parameters that needs to be passed in multi-part & normal HTTPS POST request :

Parameter Value
Description
apikey
string
Mandatory. Uniquely identifies the web-application in which the Zoho Service editors are integrated.
output string
Mandatory. Determines the format in which the Zoho Service output will be sent.

Possible values : view, editor, viewurl, url
Default value : url
mode string Mandatory. Defines access privilege for the user when opening the document in Zoho Service editors.

Possible values : view, normaledit, collabview, collabedit

view -- Document opens in read-only mode

normaledit -- Document opens exclusively in edit mode for the user and no other collaborator is allowed

collabview -- Document opens in collaborative view mode. Multiple users can view the contents of the document at the same time and can leave notes/comments using the integrated chat service. However, they cannot edit the document content.

collabedit -- Document opens in real-time collaborative edit mode. Multiple user can edit the document at the same time.
filename
string
Mandatory. Name of the document with proper file extension.

Supported values for documents: doc, docx, rtf, odt, htm, html, txt
Supported values for spreadsheets: xls, xlsx, ods, sxc, csv, tsv
Supported values for presentations: ppt, pptx, pps, ppsx, odp, sxi
documentid
long integer or string (returned by Zoho)
Unique Id of the document for identification purpose. In case of user failing to provide a documentid, Zoho Servers will generate one automatically in the form of an encrypted string.
lang
string
Optional. Lang parameter enables each Zoho Service (Writer/Sheet/Show) to offer its remote editor interface in another language.

Default value: en (English)

For a full list of languages supported by Zoho Service remote editors, please click here.
skey (deprecated)
string Optional. The secret or secure key value that needs to be passed for accessing Zoho editor urls over https.

Note: Use only the 'api key' parameter to access Zoho Services over https.
id
string
Mandatory. Unique handback id or doc session id that integrators/users need to provide when sending request to Zoho for opening a particular document. 

The 'id' parameter can be used to store all relevant document-related information, including session id, list of shared users, doc id etc. as an encoded string.

The info in 'id' parameter will be returned to the 'saveurl' by Zoho Document Servers whenever 'save' is invoked by the user.

Use-case: By providing shared user info in the 'id' parameter, a developer or a saveurl handler of the Zoho-integrated application will get to know which shared user has saved a document during collaboration.
format
string
Mandatory. The format in which the document needs to be saved back to the enterprise document repository.

Supported values for documents : doc, docx, html, pdf, htm, odt, rtf, txt
Supported values for spreadsheets : xls, xlsx, ods, sxc, csv, tsv, pdf
Supported values for presentations : ppt, pptx, pps, ppsx, odp, sxi

Note: The document can be pushed from enterprise server to Zoho Service editors in one format (say doc) and saved back to their original location in different format (say pdf).
saveurl
string
Mandatory. [Enterprise Server Web URL] - The saveurl is a publicly accessible web url which should be a service that fetches the content of the updated document from Zoho Document Servers and saves it to the location specified in enterprise document repository.

Note: The saveurl specified over https/http url scheme should be a public accessible, proper domain name with its port set to 443/80. Setting IP Address as saveurl value is not advised and will return an error.

Also, please ensure that the value provided for the 'saveurl' parameter is without spaces. Saveurl value containing spaces will throw an error and the file will not get saved.

Example - https://xyz.com/docs/save.php. 
persistence
(deprecated)
boolean
Optional. persistence = true has been deprecated and the default value of this parameter is now set to false.

What this means is,
 a copy of the document will temporarily reside on Zoho's document servers as long as you have the document open in Zoho editor. After you save & close the document session, the copy is automatically removed from Zoho's document servers.

Specific Parameters

For multi-part form submit:

Parameter Value
Description
content
string
Mandatory. Actual document content to be uploaded to Zoho Service editors. If there is no content, a new document will be created.

For normal form submit:

Parameter Value
Description
url
string
Mandatory. A publicly accessible web url from which the Zoho Service editor can fetch the document content.

Note: It is mandatory to specify the absolute path of the document in url parameter with proper file extension.

Also, the port of the document web-url should be set to '443' when sending the request to Zoho over https url scheme.

Example: https://xyz.com/documents/mysample.doc.

Output parameter values *

The output parameter decides the format in which output is sent from Zoho document servers. This is in response to the request sent by the enterprise server for opening the document. Currently, Zoho allows four different values for the output parameter.

  1. url: with "url" as the output parameter value, developers will get a response of the document in form of a url. The document url can then be sent from the enterprise server to the client-side (user's web browser) for opening the document content in Zoho service editors for editing purpose.
  2. viewurl: with "viewurl" as the output parameter value, the document content will be uploaded in Zoho service editors in "view-only" mode.

    Response format of url/viewurl request:
    URL=[document url value]
    WARNING=[warning message]
    RESULT=[TRUE/FALSE]

    Note: RESULT field indicates the status of the action. Zoho will return 'TRUE' if the request is posted successfully, else the
    value is 'FALSE'.

    Similarly, if any of the parameters are found to be incorrect, you will get a warning message stating the same otherwise
    the value returned will be 'NULL'.
    Sample response of url/viewurl request:
    URL=https://show.zoho.com/remoteedit.sas?doc=zPPG0w707d7wax67020x68F
    WARNING=NULL
    RESULT=TRUE
    Note: Developers who wish to access Zoho service editors from within their website can provide the output parameter 
    value as either "url" or "viewurl". In turn, the document url obtained can be added to the "src" attribute of
    "iframe" tag for embedding the Zoho editors.
  3. editor: when you pass "editor" as the output parameter value, the response is redirected to the editor page from Zoho Sheet & Zoho Show servers. In the other hand, Zoho Writer returns a javascript code snippet that automatically opens the Writer editor with the document content for editing.
  4. view: with "view" as the output parameter value,  the response is redirected to the editor page from Zoho Sheet & Zoho Show servers. Zoho Writer returns a javascript code snippet that automatically opens the Writer editor with the document content for viewing purpose only.
    Note: Developers who wish to open the Zoho service editors in a new browser tab/window instead of embedding it in their 
    website, can provide the output parameter value as either "editor" or "view".
Errors

In case of a user missing any mandatory parameter or providing incorrect value for the same, Zoho will return exceptions in a generalized 'name-value' format.

Error response format
RESULT=[TRUE/FALSE]
ERROR_CODE
=[error code value]
WARNING=[description of the stated error]
Sample error response
RESULT=FALSE
ERROR_CODE=3832
WARNING=The value specified for api key is invalid.
For a complete list of Error Codes, please click here.


Multi-part Form Submit - Sample
<form method="POST" action="https://exportwriter.zoho.com/remotedoc.im" enctype="multipart/form-data" target="_self" 
accept-charset="UTF-8">
File : <input type="file" name="content" size="38"> <br>
<input type="hidden" name="apikey" value="[Zoho_API_Key]">
<input type="hidden" name="output" value="url">
<input type="hidden" name="mode" value="normaledit">
<input type="hidden" name="filename" value="mydocument.doc">
<input type="hidden" name="lang" value="[en/fr/de/ja/it...]">
<input type="hidden" name="id" value="12345678">
<input type="hidden" name="format" value="doc">
<input type="hidden" name="saveurl" value="[https://xyz.com/docs/save.php]">
<input type="submit" name="submit" value="Open/Edit">
</form>
 Normal Form Submit - Sample
<form method="POST" action="https://exportwriter.zoho.com/remotedoc.im" target="_self" accept-charset="UTF-8">
<input type="hidden" name="url" value="[https://xyz.com/office/documents/mysample.doc]">
<input type="hidden" name="apikey" value="[Zoho_API_Key]">
<input type="hidden" name="output" value="url">
<input type="hidden" name="mode" value="normaledit">
<input type="hidden" name="filename" value="mydocument.doc">
<input type="hidden" name="lang" value="[en/fr/de/ja/it...]">
<input type="hidden" name="id" value="12345678">
<input type="hidden" name="format" value="doc">
<input type="hidden" name="saveurl" value="[https://xyz.com/docs/save.php]">
<input type="submit" name="submit" value="Open/Edit">
</form>
Important Note: We recommend that developers send the request to Zoho as an emulated multi-part form (HTTPS POST) from their enterprise server. This is for the simple reason that, if the request is sent from the server, the api key is not exposed to the client side and will not be subjected to third-party hacks. The work flow for the whole of request goes like the one below :

Document Open/Edit Visual Workflow




    Steps :
    1. User visits partner web portal that has Zoho remote api integrated and places a request for opening a document.
    2. The request, for opening the document, is sent as a multi-part form (HTTPS POST) from partner's server to Zoho's document servers.
    3. Zoho, in turn, returns the url of the document to partner's server.
    4. The document url is then sent from partner's server to the client side (user's browser).
    5. User's browser uploads the doc content in Zoho editor.


Guest 1422 - days ago 
Way to go, Zoho!
Guest 1402 - days ago 
It would really help if you could document what is returned from the server when you specify output=url, especially what kind of errors can be returned.
rahuldas78 1026 - days ago 
I have tried to open spreadsheet but it is showing error. I have integrated the form as mentioned above with POST url and when the page is redirecting to https://sheet.zoho.com/remotedoc.im, it is showing error.

any ideas?

Rahul Das
rahuldas78@gmail.com
Guest 946 - days ago 
Do you have C# version of the code using httpwebrequest or the like? Thanks.

Crysta Morales
clemorales@yahoo.com
sar2411 763 - days ago 
<form method="POST" action="https://exportwriter.zoho.com/remotedoc.im?output=editor" enctype="multipart/form-data"
target="_self" accept-charset="UTF-8">
File : <input type="file" name="content" size="38"> <br>
<input type="hidden" name="apikey" value="[zoho_api_key]">
<input type="hidden" name="mode" value="edit">
<input type="hidden" name="documentid" value="1877099822">
<input type="hidden" name="format" value="doc">
<input type="hidden" name="filename" value="mydocument.doc">
<input type="hidden" name="id" value="aaa">
<input type="submit" name="submit" value="Edit">
</form>
anishmninan 696 - days ago 
when i used the plugin in the following format
<form method="POST" action="https://show.zoho.com/remotedoc.im" enctype="multipart/form-data" target="_self" accept-charset="UTF-8">
File : <input name="content" size="38" type="file">

<input name="apikey" value="[zoho_api_key]" type="hidden">
<input name="output" value="editor" type="hidden">
<input name="mode" value="normaledit" type="hidden">
<input name="filename" value="test.pptx" type="hidden">
<input name="lang" value="en" type="hidden">
<input name="id" value="12345678" type="hidden">
<input name="format" value="pptx" type="hidden">
<input name="saveurl" value="save.php" type="hidden">
<input name="submit" value="Open/Edit" type="submit">
</form>
I can't view the presentation file. It shows a message like

"RESULT=FALSE
ERROR_CODE=3832
WARNING=The value specified for saveurl is invalid."

but i have used the same savedoc.php for documents as well as the excel sheets for saving. Please help i need to integrate and find out a solution.
coldfusionguy 508 - days ago 
<form method="POST" action="https://sheet.zoho.com/remotedoc.im" target="_self" accept-charset="UTF-8">
<input type="hidden" name="url" value="http://jpf1.my.phpcloud.com/Databases/exceldocs/03formulas.xlsx">
<input type="hidden" name="apikey" value="999999999999">
<input type="hidden" name="output" value="url">
<input type="hidden" name="mode" value="normaledit">
<input type="hidden" name="filename" value="03formulas.xlsx">
<input type="hidden" name="lang" value="en">
<input type="hidden" name="id" value="22345678">
<input type="hidden" name="format" value="xlsx">
<input type="hidden" name="saveurl" value="https://xyz.com/docs/save.php">
<input type="submit" name="submit" value="Open/Edit">
</form>

I tried the above and I get a response like below:
RESULT=TRUE
URL=https://sheet.zoho.com/editor.do?doc=c2826da1f9894a549f13cf1172e390a30cabeb061f45f393&lang=en

But where is the document? I am expecting to see it inside a web browser using ZOHO sheet. Is something missing?
ngunnawaljack 492 - days ago 
When I use the editor for a MS Word file with relatively minor complexity as in an academic essay, the saved document has the format and page numbering corrupted and the foot notes stripped out.
dkaminski 343 - days ago 
coldfusionguy, I get the same thing... what do you do with the response URL?
Sriram Raghunathan 317 - days ago 
Hi dkaminski,

The response URL is the one which load the Sheet Editor used for Editing the XLS(X) file.
chris 257 - days ago 
here's sample code showing you what to do with the response URL using php and curl:

<code>
<!--?php<br-->$urltopost = "https://exportwriter.zoho.com/remotedoc.im";
$datatopost = array (
"apikey" => "<api here="">",
"url" => "<file location="" here="">",
"output" => "url",
"mode" => "normaledit",
"filename" => "<file name="" here="">",
"lang" => "en",
"id" => "<if you="" need="" zoho="" to="" return="" something="" for="">",
"format" => "docx",
"saveurl" => "<your save="" function...which="" you="" can="" find="" an="" example="" in="" the="" zoho="" wiki="">",
);

//curl part
$ch = curl_init ($urltopost);
curl_setopt ($ch, CURLOPT_POST, true);
curl_setopt ($ch, CURLOPT_POSTFIELDS, $datatopost);
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, true);
$returndata = curl_exec ($ch);

//to see what is returned uncomment the line below this
//print ($returndata);

parse_str($returndata);
echo "iframe style="width:100%;height:100%;" src="" .$url.""="">/iframe";
?>
</your></if></file></file></api></code>
** there is one exception to this that I know of. the parse_str function only works for the exportwriter URL. If you need sheet, you'll need to use this:
$returndata = curl_exec ($ch);
substr($returndata, 12);
parse_str($returndata);
echo "iframe style="width:100%;height:100%;" src="" .$url.""="">/iframe";

For some reason zoho's sheet returns the data differently than the writer URL...dont know why. I haven't tried the show function either so that might return something different too.
meena01.acs 149 - days ago 
<form method="post" action="https://exportwriter.zoho.com/remotedoc.im?output=editor"
enctype="multipart/form-data" target="_self" accept-charset="UTF-8">
<input type="hidden" name="apikey" value="[zoho_api_key]" />
<input type="hidden" name="mode" value="normaledit" />
<input type="hidden" name="documentid" value="222" />
<input type="hidden" name="output" value="view" />
<input type="hidden" name="format" value="doc" />
<input type="hidden" name="filename" value="MyDoc.docx" />
<input type="hidden" name="id" value="aaa" />
<input type="submit" name="submit" value="Open" />
</form>
Above code is opening blank document and not giving any error.
Please help.
Its urgent.
Post a comment

Your Name or E-mail ID (mandatory)

Note: Your comment will be published after approval of the owner.





 RSS of this page