Document Edit Protection

💡 API calls require authentication. Refer to Interface Authentication for authentication

POST {apiPrefix}/protect

Submit document edit protection task

• If task addition fails, the failure reason is returned synchronously
• If task addition succeeds, the task ID is returned synchronously. Third parties can configure task callback notifications to get task status.
• Source file maximum 300M

Request Body:

Content-Type is application/json

Parameter Name	Type	Description	Required
callback	string	Callback address. zOffice will callback to notify status after task completion	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
filename	string	File name, must have extension, only supports doc/docx/wps. Source file maximum 300M	Yes
fileUrl	string	File download path	Yes
protectionAct	string	enable: enable protection (set document to read-only, password required to enable editing); disable: disable protection	Yes
password	string	Edit password, first encrypt with AES/ECB/PKCS7Padding, then base64 encrypt.	No

• For fileUrl/tokenType/tokenValue/callback description, see Common Field Description in this document
• Password encryption example see "Password Encryption Java Code Example" below. The key used for encryption is automatically generated when enabling OpenAPI in the integrated application of the management console, and can be reset, viewed, or copied within the console.
• If the document has already enabled edit protection, please confirm the execution effect is what you want. See the effect summary below.

Normal Response:

{
    "taskId": "6f6598c8-c87e-420b-b6c4-6f1b187201dc",
    "code": "Ok",
    "detail": {
        "taskStatus": "IN_QUEUE"
    }
}

Error Response:

{
    "taskId": "695fbf6e-90d2-42ba-83d5-00e81e5e366e",
    "code": "TaskQueueCongestion",
    "detail": {
        "taskStatus": "FAIL"
    }
}

Execution Effects in Various Situations:

If the document has already enabled edit protection, please confirm the execution effect is what you want.

Document Status Before Execution	API Call Type	Document Status After Execution
Edit protection disabled	Enable protection	Edit protection enabled, mode is read-only
Edit protection disabled	Disable protection	Edit protection disabled
Edit protection enabled	Enable protection	Password becomes the password set by API, mode becomes read-only (regardless of previous mode)
Edit protection enabled	Disable protection	Edit protection disabled (regardless of previous mode)

Password Encryption Java Code Example:

import java.nio.charset.StandardCharsets;
import java.security.Security;
import java.util.Base64;
import javax.crypto.Cipher;
import javax.crypto.spec.SecretKeySpec;
import org.bouncycastle.jce.provider.BouncyCastleProvider;

public class Aesdemo {

    static {
        Security.addProvider(new BouncyCastleProvider());
    }

    private static final String SECRET = "AES";
    private static final String CIPHER_ALGORITHM = "AES/ECB/PKCS7Padding";
    public static void main(String[] args) throws Exception {
        // secret is the key, must match LS_DOCSCOMMON_3RD_PARTY_INTEGRATION_THIRDPARTY_0_SECRETS_RAND32 configured in zoffice, must be 32 characters
        String secret = "00000000000000000000000000000000"; 
        String password = "123456";
        // Encrypt
        Cipher cipher = Cipher.getInstance(CIPHER_ALGORITHM);
        byte[] keyBytes = secret.getBytes(StandardCharsets.UTF_8);
        cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(keyBytes, SECRET));
        byte[] doFinal = cipher.doFinal(password.getBytes(StandardCharsets.UTF_8));
        String enp = new String(Base64.getEncoder().encode(doFinal));
        System.out.println(enp);
        // Decrypt
        Cipher cipher2 = Cipher.getInstance(CIPHER_ALGORITHM);
        cipher2.init(Cipher.DECRYPT_MODE, new SecretKeySpec(keyBytes, SECRET));
        byte[] doFinal2 = cipher2.doFinal(Base64.getDecoder().decode(enp));
        String dep =  new String(doFinal2);
        System.out.println(dep);
    } 
}