Skip to main content

Quick Start

1. Preparation​

Before you start integrating, configure the business system information in the admin console (business system repoId/appId, callback context, API token name, etc.). See: Preparation.
It is also recommended to read: Important Terms, to ensure concepts and constraints such as docId, repoId, and context are aligned.

2. Implement Callback APIs​

For preview (view), you must implement:

For editing (edit), in addition to the above, you must also implement:

Callback URL format (Get File as an example)​

The Get File API should be:

{context}/{docId}/content

Where:

  • context: the callback context configured in the admin console (usually your business system API prefix)
  • docId: the unique file ID in your business system (must be stable and globally unique)

For example, if context is http://demo:8000/context, then the Get File API is:

http://demo:8000/context/{docId}/content

This API should respond with the file stream. It is recommended to test the URL directly in a browser (with required auth) to verify the file can be downloaded correctly.

3. Open the Online Document Page​

The online document page URL format is:

http://{zoffice_hostname}:8001/docs/app/{repoId}/{docId}/edit/content?{token_name}={token}

Where:

  • repoId: the third-party application ID configured in the admin console
  • docId: the document ID in your business system
  • token_name: the token parameter name, default is zdocs_access_token
  • token: the access token (a placeholder token is still required even if your callback APIs do not validate it, otherwise requests will fail)

How to pass the token​

You can either:

  • pass token_name/token in the URL query; or
  • put the token into a Cookie
  • send the token in the request body. See Security

When the document platform calls your callback APIs, it will also pass the token via Cookie.

You can open the page in a new tab, or embed it into your system using an iframe.

The following is an iframe example using GET. If you want to use POST, see Security.

iframe example​

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <style type="text/css">
    iframe {
        width: 100%;
        height: 100%;
        position: absolute;
        top: 0;
        left: 0;
        right: 0;
        bottom: 0;
        margin: 0;
        border: none;
        display: block;
    }
    body {
        margin: 0;
        padding: 0;
    }
  </style>
</head>
<body>
<div>
  <iframe
    id="integration-frame"
    src="http://zofficehost:8001/docs/app/repoId/docId/edit/content?token_name=token"
    allowfullscreen="true"
    allow="fullscreen *">
  </iframe>
</div>
</body>
</html>
Last updated on