Practical Tutorial on Jushuitan Store Master Data Sync Strategy: From Query API to Qeasy Implementation

What This Strategy Solves

In supply chain integration projects, store master data is the "foundation" from which upstream e-commerce platforms push business documents downstream. In one real engagement, a retail enterprise used Jushuitan to manage front-end stores and a private-cloud ERP for back-end finance and inventory. When store data was maintained manually, within three months the store codes, groups, and company entities on both sides drifted apart, and outbound delivery documents could no longer find the matching store.

The "Query Jushuitan Stores" strategy is meant to pull and persist Jushuitan store master data on a schedule, serving as the source of truth for downstream sync chains. On the Qeasy data integration platform, this strategy is typically scheduled early in the master data layer, running ahead of more complex strategies for products, orders, and customers.

Data Flow and Field Mapping

The overall flow is "Jushuitan → Qeasy integration platform → target storage." The source is the Jushuitan open platform's /open/shops/query endpoint; the target on Qeasy is configured as a "no-op write" that persists records into the intermediate layer for downstream strategies to reference.

Key field mapping:

The source endpoint is POST with paginated retrieval. Qeasy merges each page's response before writing to the intermediate layer. idCheck is disabled on the source but enabled on the target, meaning duplicate pulls are tolerated upstream, but deduplication by primary key happens before persistence.

How to Configure on Qeasy

When configuring this strategy on the Qeasy data integration platform, several typical points matter:

1. Platform and endpoint registration. Select Jushuitan as the source platform, set the path to /open/shops/query, method POST, and effect QUERY. The target is the Qeasy integration platform itself, effect EXECUTE, with an empty request body—the purpose is to persist store records into the intermediate database for subsequent strategies to query.

2. Primary key and number field. Set both source number and id to shop_id, so Qeasy can use the same field for idempotency checks, preventing duplicate writes during paginated retrieval.

3. Response mapping. Enable autoFillResponse so the platform auto-maps response fields to the target model. There's no need to hand-write mapping scripts—store master data fields are stable, and auto-mapping is the safest choice.

4. Scheduling. In the source material, the source crontab is 38 3 * * * (03:38) and the target is 23 2 * * * (02:23). This is a common pattern among Qeasy customers—scheduling the target before the source—so the intermediate database is emptied first and then refreshed. This simplifies troubleshooting by separating write issues from pull issues.

Implementation Steps

We recommend a three-phase rollout:

Phase 1: Full initial load. On first go-live, set page_size to its maximum of 100 and paginate through all stores. Verify that group_name, co_id, and session_uid all land correctly in the intermediate database. This phase is usually triggered manually during off-peak hours and not scheduled.

Phase 2: Switch to incremental. After verifying the full load, put the strategy on a schedule. Set the source crontab to 03:38 daily and the target to 02:23. Qeasy records the maximum update timestamp or maximum store number from each run, so subsequent runs only pull new or changed stores—entering the dual-track phase of incremental and full loads.

Phase 3: Stabilize scheduling. Watch logs for a week to confirm pagination boundaries, retry logic, and deduplication all behave correctly. Then include this strategy as a prerequisite dependency for downstream order and delivery sync strategies. If fields change later, only adjust the response mapping; the strategy itself need not be rewritten.

Pitfall Recap

1. Ignoring the page size cap. The /open/shops/query endpoint silently truncates page_size above 100. The safe approach is to hard-code page_size to 100 on Qeasy rather than relying on defaults.

2. Duplicate writes from the primary key. Source idCheck is off, so the platform doesn't deduplicate upstream. If target idCheck is also off, the same store can be persisted multiple times across page boundaries. A typical mistake is leaving both off—the correct setup is off upstream, on downstream, deduplicating by shop_id.

3. Time zone and schedule ordering. Source at 03:38 and target at 02:23 may look odd, but it deliberately puts the target's clear action before the source's pull. Swapping the order causes "pull-while-write" scenarios that leave stale data in the intermediate database.

4. Misreading field semantics. group_name looks like a "store name" but is actually a group name; shop_id is the real unique identifier. This is where projects often go wrong. We recommend adding Chinese aliases on Qeasy so reviewers don't rely on English names alone.

5. Centralized encoding mapping. Once store master data is stable, downstream strategies often need to map shop_id to the ERP-side store code. Maintain a centralized mapping table on Qeasy rather than hard-coding the mapping in each downstream strategy.

When to Use and When Not to Use

Use this strategy when: e-commerce and ERP are integrated, store data is maintained only in Jushuitan, and there are subsequent order or delivery documents flowing back to the ERP.

Avoid this strategy when: store master data is maintained on the ERP side and Jushuitan only receives it, or when the store count is so small that automation adds no value.