Authoritative Tutorial on the DingTalk Department Query API: Cross-Scenario Field Manual

What This Endpoint Solves

In Kingdee Cloud Galaxy–DingTalk integration scenarios, "departments" form the master-data backbone for org-structure sync: employee affiliation, approval-flow department pickers, and data-permission isolation all rely on them. topapi/v2/department/listsub is a lightweight endpoint on the DingTalk Open Platform that lists the direct sub-departments of a given parent. We use it to walk the DingTalk org tree level by level and then map it to Kingdee departments, avoiding the performance and authorization risks of a single recursive pull.

Endpoint Capability Overview

• System: DingTalk Open Platform
• Path: topapi/v2/department/listsub
• Method: POST
• Authentication: AppKey/AppSecret exchange for an access_token, which is then used for authorization. In Qeasy Cloud, this is typically configured in "App Credential" mode, with the platform handling token caching and refresh.
• Request parameter: dept_id (parent department ID; optional, defaults to 1 for the root). Only direct sub-departments are returned; grandchild or deeper levels are not.
• Response structure: A JSON array; each record contains the department primary key, name, parent ID, and corp-group flags.
• Pagination / increment: The endpoint itself does not paginate; it returns all direct sub-departments of the parent in one shot. Incremental sync is achieved on the client side by recursively polling with dept_id.
• Strategy type: QUERY (read-only; does not write to the target system). Typical scheduling: every 45 minutes between 08:00 and 22:00 (crontab: 5-59/45 8-22 * * *).

Typical Field Mapping

How to Configure It on Qeasy Cloud

In the Qeasy Cloud Data Integration Platform, this endpoint is typically wrapped as a "DingTalk Department Query" adapter. The typical configuration flow is:

1. In "Data Source", select DingTalk and fill in the app's AppKey, AppSecret, and CorpId. The platform takes over access_token acquisition and failure retry.
2. After selecting the target (Kingdee Cloud Galaxy in this scenario), set the strategy type to QUERY and set dept_id's default value to 1.
3. In the Field Mapper, map dept_id to Kingdee department's "Code" field and name to "Name". Qeasy Cloud automatically handles empty strings and encoding.
4. To recursively pull the entire org tree, use Qeasy Cloud's "Loop Call" or "Parent-Child Strategy Orchestration": feed the dept_ids returned in the current round into the next round until the queue is empty.
5. Configure the schedule based on business peaks. A common pattern is every 45 minutes during working hours with reduced frequency or a stop at night.

Cross-Scenario Practical Points

From multiple Kingdee–DingTalk integration projects, we have distilled the following common lessons:

1. Root department ID is 1: This is a hard-coded convention on the DingTalk Open Platform. Any recursive pull must start from dept_id=1; do not assume the tenant root is any other value.
2. The endpoint returns only one level; do not expect recursion: Don't be misled by documentation into expecting sub_dept_id_list for a full tree. It only returns direct sub-departments, so the recursion logic must be implemented on the caller side.
3. Use dept_id as primary key, name for display only: Names can be edited by admins at any time; cross-system mapping must anchor on dept_id.
4. Corp-group fields are mostly DingTalk-side behaviors: They usually have no meaning on the Kingdee side; we recommend ignoring them in the Qeasy Cloud field mapper to avoid dirty data being pushed.
5. Schedule frequency and login state: A 45-minute interval keeps up with department changes without triggering DingTalk's rate limits. Stopping at night reduces token-expiry alert noise.
6. Distinguish 401 from business errors in retries: An expired access_token is a retryable error and Qeasy Cloud refreshes it automatically. Business errors such as a deleted department should be routed to a dead-letter queue for manual intervention.

Pitfall Recap

1. Using name as the primary key: A retail customer originally associated departments by name. After an admin renamed them, duplicate departments appeared on the Kingdee side, and it took two full weeks to clean up. The safe approach: always anchor cross-system association on dept_id, using name only for display.
2. Expecting the entire tree in one call: A customer testing in a staging environment found that the endpoint returned only one level and mistook it for a permissions issue, repeatedly applying for enterprise super-admin. The reality is that this is by design; BFS/DFS recursion must be implemented on the caller side.
3. Ignoring type differences in corp-group fields: Depending on the DingTalk version, create_dept_group may be a boolean or the strings "true"/"false". Qeasy Cloud's field mapper must enable "lenient type parsing" or writes will fail.
4. Schedule too tight, causing token jitter: A manufacturing customer initially scheduled every 5 minutes, which triggered DingTalk's rate limit. The resulting frequent access_token refresh actually degraded overall stability.
5. Orphan nodes after a department is deleted: After a department is deleted on the DingTalk side, "orphan departments" can appear on the Kingdee side if there is no synchronized deactivation. We recommend adding a "compare-and-delete" step in the Qeasy Cloud strategy to disable any department that no longer exists on the source.

When to Use It

If you need to sync the DingTalk org structure into Kingdee, build a department picker, or map employee affiliation, this endpoint is the most reliable read-only entry point. However, it only supports one-level queries; if you need to pull the full tree at once, you must implement recursion on the caller side. If you need to write to DingTalk departments, switch to a write-class endpoint such as topapi/v2/department/create.