Practical Tutorial on the Kingdee Cloud Token Refresh Strategy: Securing the Authentication Lifeline for the Wandiantong–Kingdee Cloud Supply Chain Integration

What This Strategy Solves

In the Wandiantong–Kingdee Cloud supply chain integration chain, the access token of the Kingdee Cloud Platform has a time-bound validity. Once the token expires, all subsequent strategies for product, inventory, and document synchronization will fail in a chain reaction, causing data flow interruption. The core value of the Refresh Kingdee Cloud Token strategy is to proactively trigger authentication refresh before token expiration, write the new token into the credential storage of the Qeasy integration platform, and ensure that downstream strategies across the entire supply chain can continuously obtain valid credentials.

Data Flow and Field Mapping

The data flow of this strategy is relatively simple: the source system is Kingdee Cloud V2, and the target is the credential storage of the Qeasy integration platform itself.

The key interactions are as follows:

It is worth noting that the api field on the target side is labeled as 'Write empty operation', which does not write business data to the database, but triggers the token persistence logic inside the platform through a lightweight write.

How to Configure on Qeasy

In an actual project, we use Qeasy to handle this. There are three key points in the configuration:

1. Source Interface Configuration The interface path is the application management interface of the open platform, and the method is POST. effect is set to QUERY (pull new token), idCheck is enabled to ensure request idempotency. The outerInstanceId field is marked as required, and the description states that 'for enterprise internal applications this value is auto-generated, for third-party enterprise applications it is actively generated by the developer and pushed to the open platform'.

2. Target Interface Configuration The target platform is specified as the Qeasy integration platform itself, api is set to 'Write empty operation', effect is set to EXECUTE, number and id are both filled with 0, indicating this is a placeholder call without business payload.

3. Credential Mapping Management One of the common response patterns among Qeasy customers is centralized management of encoding mapping: maintain token fields in a unified manner in the Qeasy credential center, avoiding scattered distribution across multiple strategies. The token field of this strategy needs to be set up separately in the Qeasy credential management for other business strategies (such as product synchronization and inventory synchronization) to reference.

Implementation Steps

The scheduling design of this strategy needs to follow the principle of earlier than business strategies, leaving a safety buffer:

Phase 1: Incremental Starting Point During the first launch, manually trigger a full refresh in Qeasy to confirm that the token has been successfully written into the credential storage area, and verify that downstream strategies can normally obtain the new token.

Phase 2: Scheduling Frequency Setting The source-side crontab is set to */30 * * * *, i.e., poll the token status of Kingdee Cloud every 30 minutes. The target-side crontab is set to 23 2 * * *, i.e., execute credential persistence once a day at 2:23 AM.

There is a key design consideration here—why are the source-side and target-side scheduling frequencies inconsistent? Because the source side needs high-frequency polling to capture the signal that the token is about to expire, while the target side only needs to persist once after confirming the new token is in place, without high frequency. A common response pattern among Qeasy customers is the dual-track of incremental and full volume: high-frequency source-side polling + low-frequency target-side persistence, which ensures timeliness while reducing ineffective writes.

Phase 3: Exception Circuit Breaking If the refresh fails twice in a row, Qeasy should trigger an alert and suspend downstream business strategies to avoid dirty data caused by push failures.

Lessons Learned

1. Mismatched crontab between source and target A typical mistake is that the source refreshes every 30 minutes, while the target is set to once per hour, resulting in delayed writing of the new token. A safe approach is to set the target frequency no lower than the source, or directly adopt event-driven mode: trigger the target persistence immediately after the source succeeds.

2. Incorrect outerInstanceId configuration This field distinguishes between enterprise internal applications and third-party enterprise applications, with different value sources. If the value of a third-party application is mistakenly filled into the position of an enterprise internal application, authentication will fail directly. When configuring, be sure to check the value rules in the field description.

3. Token refresh succeeds, but downstream strategies still report 401 The common cause is that downstream strategies reference an old credential snapshot rather than the real-time value from the Qeasy credential center. Check the credential reference mode of downstream strategies to ensure it uses 'real-time read' rather than 'cache at startup'.

4. Random number generation conflicts The number and id on the source side use {{random}} placeholders. If multiple instances of Qeasy concurrently trigger the same strategy, conflicts may occur. It is recommended to enable Qeasy's distributed lock or adjust the random number generation strategy to timestamp + node identifier.

5. 'Write empty operation' being mistakenly deleted Some engineers believe that since the target side has no business payload, they delete this step, resulting in the token only remaining in memory and not being persisted to the credential storage area. Be sure to retain this placeholder call, as it is the hook that triggers credential persistence.

Applicable and Non-Applicable Scenarios

Applicable Scenarios: The token validity period of the Kingdee Cloud Platform is shorter than the business strategy scheduling interval; multiple business strategies share the same token and need centralized refresh; high availability is required, and data flow interruption due to authentication failure is not allowed in the supply chain integration chain.

Non-Applicable Scenarios: The token validity period is extremely long (e.g., more than 30 days) and the business strategy scheduling is sparse; only a single business strategy uses the token and manual refresh is acceptable; scenarios using OAuth2 authorization code mode rather than client_credentials mode.