FAQ

​

Onboarding

​

How to obtain the workbookId of a Spreadsheet

• From the Spreadsheet URL: Open the Spreadsheet. The Document ID contained in the URL is the workbookId.
• From the document information: In the upper-left corner of the Spreadsheet, click Menu → Spreadsheet → Document Information. The Document ID shown there is the workbookId.
• Through the Knowledge Base API: Call the Get node API. The returned nodeId (dentryUuid) is the workbookId.

​

How to obtain the operatorId

1. Get the userId by phone number: Call the Query users by phone number API.
2. Get the unionId by userId: Call the Query user details API. The returned unionId is the operatorId.

​

What to do when the access token expires

• Cache the token and its expiration time.
• Proactively refresh the token 5 minutes before it expires.
• When the API returns a token-invalid error, refresh immediately and retry.

​

How to resolve the error “The operator has no permission” when calling an API

• Whether the user has access to the Spreadsheet: Make sure the user has been added as a Collaborator of the Spreadsheet, or that the Knowledge Base hosting the Spreadsheet has granted permissions to the user.
• Whether the permission type matches:
  • Read operations such as GetAllSheets, GetSheet, and GetRange require the Document.Workbook.Read permission.
  • Write operations such as AppendRows, UpdateRange, and CreateSheet require the Document.Workbook.Write permission.
• Whether the app has applied for the required permissions: In App Management on the DingTalk Open Platform, verify that the corresponding permission scopes have been applied for and approved.

​

API usage

​

Can the sheetId parameter accept a Worksheet name

• Pass the ID: Sheet1, which is system-generated.
• Pass the name: Sales Data, which is a user-defined Worksheet title.

Recommendation: Use the Worksheet ID whenever possible, because the name can be modified by users. You can call the GetAllSheets API to obtain the IDs and names of all Worksheets.

​

Where is data written when AppendRows appends data

• If the Worksheet is empty, data is written starting from the first row.
• The number of appended Columns should match the existing data to keep the data aligned.

​

What is the format of rangeAddress when using UpdateRange to update Cells

​

What is the difference between GetRange and UpdateRange

​

How to troubleshoot the error invalidRequest.resource.notFound

​

What are the usage limits of the DingTalk Spreadsheet API

​

How to handle API call failures in code

• Auto-refresh on token expiration: Catch token-invalid errors, refresh the token automatically, and retry.
• Retry on rate limiting: When a 429 error is returned, wait before retrying (we recommend an exponential backoff strategy).
• Idempotency handling: For write operations such as AppendRows, note that retries may cause duplicate data writes. Include a unique identifier in the data and verify it with GetRange after writing.
• Timeout handling: Set a reasonable timeout for network requests (we recommend 30 seconds), and retry after a timeout.

import time

def call_api_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except TokenExpiredError:
            refresh_token()
        except RateLimitError:
            time.sleep(2 ** attempt)
        except TimeoutError:
            time.sleep(1)
    raise Exception("The API call failed. The maximum number of retries has been reached.")