Development Required Reading

Interface Address Prefix

In all interface addresses below, apiPrefix represents the interface address prefix. The prefix consists of:

/docs/publicapi/{apiVersion}

• apiVersion is currently v1

The current default value is /docs/publicapi/v1

Common Field Description for Interface Request Body

Parameter Name	Type	Description	Required
fileUrl	string	File download address	Yes
tokenType	string	Third-party token type, value is cookie or header	No
tokenValue	string	Third-party token value, passed back when zOffice downloads files or callback notifications	No
callback	string	Callback address. zOffice calls back to notify status after task conversion is complete	Yes

fileUrl Description

The hostname of fileUrl needs to be consistent with the hostname of the "Third-party Application Interface Address Prefix" configured for this application in the management console.

When zOffice sends a fileUrl request to download a file, it will pass credentials according to tokenType/tokenValue below.

tokenType and tokenValue Description

• If tokenType is cookie, then tokenValue format should be key=value;key2=value2.

  • When zOffice sends a request to download a file or request a callback, the value of the request header Cookie will be set to the value corresponding to tokenValue

• If tokenType is header, then tokenValue is a string.

  • When zOffice sends a request to download a file or request a callback, the value of the request header Authorization will be set to the value corresponding to tokenValue

• If tokenType is empty, zOffice will not carry any special authentication information when downloading files.

callback Description

• After task conversion is complete, zOffice notifies the caller through callback callback. zOffice passes back to the third party when calling back.
• The hostname of callback needs to be consistent with the hostname of the third-party application interface address prefix registered on the management console The third-party system needs to implement the callback API. After the task is complete, the zOffice server calls this interface to notify the third-party system.

When the zOffice server calls this interface, it will use the authentication method described in tokenType and tokenValue

1. Handle POST requests
2. Handle Content-Type as application/json

Request body structure

{
    "taskId": "Task ID",
    "code": "Task result code",
    "detail": {
        // Detailed information
    }
}

code Description

• If the call task succeeds, code is TaskSuccessNotify or ConvertSuccessNotify;
• If the call task fails, code is TaskFailNotify or ConvertFailNotify

Task Success Notification:

{
    "taskId": "1c1cf10b-d9e6-4927-b75e-dddf6b441445",
    "code": "TaskSuccessNotify", // or ConvertSuccessNotify
    "detail": {
        "taskStatus": "SUCCESS",
        "defaultDownloadPath": "/docs/open/v1/convert/download",
        "contentId": "640eeac02a9baf5dbc69d426",
        "filename": "demo-docx.pdf"
    }
}

Task Failure Notification:

msg will describe the reason for task failure

{
    "taskId": "1c1cf10b-d9e6-4927-b75e-dddf6b441445",
    "code": "TaskFailNotify", // or ConvertFailNotify
    "detail": {
        "taskStatus": "FAIL",
        "msg": "conversion format err",
        "filename": "demo-docx.pdf"
    }
}