Zoho Office API
1. How do I open documents in Zoho service editors?
Zoho service editors, exposed through Office APIs, can be invoked by sending a simple HTTPS POST request to the specific Zoho service. Depending on the file location, local drive or web, partners can send the request to Zoho servers for opening the document in a couple of ways:
- Multi-part Form Submit - Opens documents present in your computer's local drive or desktop.
- Normal Form Submit - Opens documents present over a publicly accessible web URL.
As for sending request to Zoho service URLs, partners can use the below links based on the file type (.doc, .xls, .ppt etc):
- Zoho Writer (document) - https://writer.zoho.com/write/remotedoc.im
- Zoho Sheet (spreadsheet) - https://sheet.zoho.com/sheet/remotedoc.im
- Zoho Show (presentation) - https://show.zoho.com/show/remotedoc.im
2. I get an error while saving a document over https URL scheme. What am I doing wrong?
The stated error in saving the document will occur in any of the two cases stated below:
- SSL Certificate does not match your registered domain name. Check the authenticity of your SSL Certificate from the website: http://www.digicert.com/help/
- Partner's SSL Certificate is not part of the Sun's JRE list supported by Zoho. List of supported CAs(Certification Authority) can be found here.
3. How do I open documents in different modes (view/edit) in Zoho Service Editors?
The 'mode' parameter determines the way in which a document is uploaded to Zoho service editors. Currently, Zoho allows four different values that can be passed in the mode parameter. They are -
- view - Document opens in read-only mode.
- normaledit - Document opens in edit mode exclusively for the particular user, no other collaborator is allowed for concurrent editing.
- 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 users can edit the document as well as add notes/comments at the same time.
Note : It is mandatory to set the output parameter value as 'url' when mode is chosen as 'collabedit' during form submit.
4. What is the use of 'output' parameter? How is it different from 'mode' parameter?
The 'output' parameter decides the format in which output is sent from Zoho servers. This is in response to the request sent by partners' server for opening the document. The response for the output could be either in 'url' or 'editor' format.
Note : For Zoho integration, we recommend using 'url' as the output parameter and to send the request as an emulated multi-part form (HTTPS POST) from the partner's server. The 'editor' value can be used for testing purpose from the client-end.
List of output parameter values are:
- url - Zoho sends the response in the form of URL. Use this document 'url' in the URL web-browser to open the document in Zoho for editing purpose.
- viewurl - Response in URL format. Document opens for viewing purpose.
Important Note : With the introduction of collaboration feature in Zoho Office API, we have added a new 'mode' parameter. This 'mode' parameter has now taken precedence over the 'output' parameter. The value provided in the mode parameter overrides that of the output parameter in few of the use-cases. These are described below:
|1||Writer - Document opens in 'normaledit' mode.
Sheet - Document opens in 'view' mode.
Show - Document opens in 'view' mode.
|2||view||Document opens in 'view' mode.|
|3||normaledit||Document opens in 'normaledit' mode.|
|4||collabedit||Document opens in 'collabedit' mode.|
|5||collabview||Document opens in 'collabview' mode.|
|6||url||Document URL returned which opens in 'normaledit' mode.|
|7||viewurl||Document URL returned which opens in 'view' mode.|
|8||editor||Document opens in 'normaledit' mode.|
|9||view||Document opens in 'view' mode.|
|10||url||view||Document URL returned which opens in 'view' mode.|
|11||url||normaledit||Document URL returned which opens in 'normaledit' mode.|
|12||url||collabedit||Document URL returned which opens in 'collabedit' mode.|
|13||url||collabview||Document URL returned which opens in 'collabview' mode.|
|14||viewurl||view||Document URL returned which opens in 'view' mode.|
|15||viewurl||normaledit||Document URL returned which opens in 'normaledit' mode.|
|16||viewurl||collabedit||Document URL returned which opens in 'collabedit' mode.|
|17||viewurl||collabview||Document URL returned which opens in 'collabview' mode.|
|18||editor||view||Document opens in 'view' mode.|
|19||editor||normaledit||Document opens in 'normaledit' mode.|
|20||editor||collabedit||Document opens in 'collabedit' mode.|
|21||editor||collabview||Document opens in 'collabview' mode.|
|22||view||view||Document opens in 'view' mode.|
|23||view||normaledit||Document opens in 'normaledit' mode.|
|24||view||collabedit||Document opens in 'collabedit' mode.|
|25||view||collabview||Document opens in 'collabview' mode.|
5. If I pass in collabedit for 'mode', how do I point another user at it for concurrent editing?
First of all, you need to set the output parameter value as 'url' before sending the request to Zoho Servers via HTTPS Form POST. When you do the form post for 'User A' with output as 'url' and mode as 'collabedit', you will get a response in return with the documentid and it will be something similar to the one below:
WARNING=NULL RESULT=TRUE DOCUMENTID=4uaWNZ7T4738yaIcy5UxMN6/F4Vd
Now, use the above 'DOCUMENTID' and do the HTTPS Form POST again for the second user (say User B). You can provide a name for the shared user in the 'username' parameter for easier identification of collaborators. Once you get the response as the document URL, you can ask 'User B' to provide the document URL in the browser address bar, press enter and join 'User A' in collaborative editing mode. Similarly, invite more users to work on the document by providing the same documentid in subsequent requests.
6. Why do all the shared users in collaboration mode are listed as 'Guest'?
By default, Zoho servers identify collaborators as 'Guest' in case no username is given. For easier identification of the shared users in collaboration mode, we recommend partners to make use of the 'username' parameter, and provide names of the collaborators, when sending the request to Zoho. Once the collaborators start working on the shared document, their names will get listed on the integrated chat panel. Each shared user can see the other co-editors by clicking on the 'Collaborators' button present in the status bar of the document editor.
Moreover, the paragraph or the section of the document on which User A does the edit is color-coded and hence its easy for User B to identify which part of the document is being edited by the co-editor.
7. What is the maximum file size I can upload to Zoho?
The file size limit of a single document that can be uploaded to Zoho's office editors (Writer, Sheet & Show) is 10 MB. In case you are trying to upload a document that is greater than 10 MB, the request will fail and you'll get a timeout error as a response from Zoho.
8. What is 'id' parameter used for? Is it mandatory?
The 'id' parameter, also known as handback id, can be used by partners to pass additional information on the document when sending the request to Zoho. The doc-related info in the 'id' parameter will be returned by Zoho to the partner's document repository every time a 'Save' is invoked from the Zoho service editors. Few use-cases are:
- Get to know who has saved the document in collaboration mode.
- Any document related information that is required by the web application. This may include file type, file id, folder id where the doc needs to be saved etc.
Assign shared user information as 'JSON/XML' string in the 'id' parameter value. Zoho will return the details on which user has saved the document in collaboration mode.
Note : The 'id' parameter is mandatory and accepts 'string' value as an input. An error will be thrown if the parameter is missing.
9. Every time I send a request to Zoho, I receive 'Unable to Import Content' error? What am I doing wrong?
You will get the 'Unable to Import Content' error in either of the two cases:
- The document format is not supported by Zoho. For a full list of support file formats click here.
- Zoho is unable to resolve the file extension in the request.
To get around this problem, you need to provide a filename with proper file extension (e.g. test.doc, sample.xls etc.) in the url parameter when doing a normal-form submit. Also, ensure the 'filename' parameter contains the name of the file with the original file extension of the imported document (e.g. test.doc).
10. Why am I getting junk characters in the file name when I save a file?
The reason for receiving junk characters in file names can be because:
- The file name is in a language other than English (e.g. German, Chinese, Japanese etc.).
- The file name contains some special characters.
To offset this problem of junk characters, partners can encode the file names using the 'UTF-8' character encoding mechanism. UTF-8 or Unicode is a universal character set option that supports multilingual documents, i.e., documents whose file name or content are written in various languages (Chinese, Japanese, German etc.) other than English.
So, partners have to give 'accept-charset="UTF-8"' value while doing a Form Submit using HTTPs POST method.
11. Can I use Zoho API for writing documents in multiple languages? If so, how many different languages does Zoho support?
Yes, you can make use of Zoho service editors for writing documents in various languages. All you need to do is pass a parameter named 'lang' with appropriate value during form submit.
Currently, Zoho offers its remote editor interface in more than 20 languages. For a full list of languages supported by Zoho Service editors, please click here.
12. Why do I get a 'Connection refused from remote server' exception when I save a document?
Users will get this error when Zoho is unable to reach the partner's document repository path specified in the 'saveurl' parameter. One of the reasons could be that the document title contains spaces and the 'saveurl' value is not URL-encoded. Please URL-encode the 'savurl' parameter value to avoid this exception.
13. What are the supported file formats for Zoho Office API?
You can find the supported file formats for Zoho Office API here.
14. Why isn't my sample code working?
To make your sample code work, please replace "Zoho_API_Key" in your code with the actual API key assigned to you, right after you signed up with Zoho.