Jushuitan Token Refresh Strategy Tutorial: The Credential Renewal Mechanism in Supply Chain Integration

What This Strategy Solves

Jushuitan's open platform uses OAuth-style short-lived tokens that typically expire within a few hours. Once a token expires, every downstream strategy — customer lookup, material sync, sales order push — instantly stalls, and the business side only sees "reconciliation mismatches." The token refresh strategy acts as a night watchman for the entire integration: it periodically swaps an expiring token for a fresh one, writes it back into the Qeasy integration platform's credential vault, and ensures the remaining 27 strategies always hold a working key.

Data Flow and Field Mapping

This strategy carries almost no business payload. The source is the Jushuitan open platform; the target is the credential store inside the Qeasy integration platform.

The four fields that actually get consumed from the source response are name (warehouse name), co_id (main warehouse company ID), wms_co_id (sub-warehouse ID), and is_main (boolean). They are not used for master-data sync; they confirm which warehouse this new token belongs to, which is essential for later sales-order routing in multi-store scenarios.

How to Configure It in Qeasy

Setting up this strategy in the Qeasy data integration platform usually takes three steps.

Step 1, create a new strategy with Jushuitan as the source platform and the Qeasy integration platform as the target. Pick the "credential maintenance" or combined "QUERY + EXECUTE" type. The source API is refresh.token with POST method; the target is a write-empty-op, whose purpose is to leave a trace in the execution log so you can audit when each refresh happened.

Step 2, in the source request body, put only two things: the long-lived app_key and the latest refresh_token. We strongly recommend keeping both inside Qeasy's credential manager rather than hard-coding them into scripts — this is one of the most common patterns we see among Qeasy customers: centralize all codes, secrets, and tokens in the platform, never scatter them across strategies.

Step 3, in the response parser, capture access_token, refresh_token, and expires_in, and overwrite the same set of keys in the credential vault. The next refresh cycle will use the freshly issued refresh_token as input, creating a rolling renewal loop.

Implementation Steps

On customer sites, we usually walk through three phases.

Phase 1 — Incremental Start: First Authorization. Complete one manual authorization in the Jushuitan backend to obtain the initial refresh_token, then register it in the Qeasy credential vault. This is the starting point of every later automatic refresh and must be verified.

Phase 2 — Full Trigger: Run Once Manually. After configuration, manually trigger the token refresh strategy once and confirm that a new access_token is returned and that the credential vault values are actually overwritten. A common pitfall at customer sites is: the strategy reports success, but the credentials are not written back — usually because the target "write-empty-op" placeholder forgot to tick "auto-persist."

Phase 3 — Scheduling Frequency: Periodic Renewal. The reference cron in the source material is 1 2 7,8,9 11 *, set in the early morning of the first few days of the month. We more commonly recommend a rolling cron that fires 30 minutes before the token actually expires, e.g. 0 */2 * * *. Incremental and full-track dual mode is another frequent pattern among Qeasy customers: token refresh runs on a "small-step fast" schedule, while business data sync runs on "event-driven + scheduled fallback." The two legs do not interfere with each other.

Pitfalls We Have Seen

1. The refresh_token itself expires. Jushuitan's refresh_token is not "valid forever"; it will die after long idle periods. The safe approach is to add a failure alarm inside the strategy: if two consecutive refreshes fail, push a notification into the enterprise WeChat or DingTalk group so ops can intervene.

2. Tokens get crossed between warehouses. A real customer scenario: multiple subsidiaries under one group each authorized separately, but all refresh strategies pointed to the same credential set, causing tokens to overwrite each other. Centralized credential mapping here must be partitioned by subsidiary, each with its own independent credential set.

3. Cron sits on a business peak hour. Scheduling the refresh exactly on the hour makes every downstream strategy fight for the same new token at the same moment, creating a traffic spike. Off-peak hours at irregular minutes — like the 1 2 ... pattern in the source material — avoid this "collective lock change."

4. The write-empty-op is mistaken for a bug. The placeholder action on the target looks like it does nothing, but in reality it acts as the log anchor for "this refresh has happened." Delete it, and you will lose a timestamp during later audits.

5. Dependency ordering is not wired up. Inside a 27-strategy solution, the token refresh must run first, with sequence A or an empty dependency list. The typical mistake is to schedule it in parallel with business strategies, so the very first sync attempt still uses the stale token.

Where This Applies and Where It Does Not

Applies to any supply chain integration that calls Jushuitan open APIs, especially retail and distribution scenarios with multiple strategies, warehouses, or stores. Does not apply to fully self-contained Jushuitan internal integrations (no external credential needed) or to one-off ad-hoc data exports (manual authorization is enough; no automation required).