Practical Tutorial on the Jushuitan Shop Query Sync Strategy

What this strategy solves (scenario and value)

In e-commerce and supply chain integration projects, shop master data is non-negotiable basic information. In one real project, a retail enterprise ran multiple e-commerce platforms at the same time, and the "shop" fields of offline stores, online stores and franchise stores were scattered across platforms. The downstream ERP could not get a unified record when generating sales orders, stock summaries and transfers, so it had to be maintained manually, and within three months the numbers on both sides no longer matched. The core value of the Jushuitan shop query strategy is to pull shop records from upstream platforms into the integration layer at a unified cadence, and serve as the master-data source for subsequent document sync and stock aggregation.

Data flow and field mapping (source → middle layer → target)

The data flow of the strategy is straightforward: the source is Jushuitan, which calls the open interface /open/shops/query to fetch the shop list; the middle layer goes through the Qeasy data integration platform for pagination and storage; the target is a "write null operation" node of the Qeasy integration platform itself, used mainly to trigger the dependencies of downstream strategies.

The source-side input parameters are not complicated, typical configuration is as follows:

Key fields returned by the source include group name, company code, session user id, etc. In Qeasy, we are used to drawing up a field mapping table, listing all fields that need to be pushed downstream first, and then deciding which ones go into the master record and which ones are for reference only.

How to configure it on Qeasy

On the Qeasy data integration platform, this strategy is modeled as a pair of source/target configurations:

• Source: platform Jushuitan, interface /open/shops/query, pagination parameters page_index / page_size, response auto-expanded;
• Target: a "write null operation" node, only used to register dependencies and trigger downstream, avoiding orphan strategies with "source but no target";
• Crontab: source */20 * * * *, target 23 2 * * *, staggered trigger;
• Metadata switches: buildModel=false, idCheck=false, autoFillResponse=true, matching the pure query + null landing form.

We centrally manage code mapping in Qeasy's "Mapping Center": make a maintainable mapping table between Jushuitan's co_id and the ERP internal company code, instead of scattering it in scripts. This "centralized code mapping" approach is the most common pattern among Qeasy customers, and only one place needs to be modified when a company splits or merges later.

Implementation steps (phased scheduling)

We usually divide such master-data sync into three phases:

1. Incremental start point: run one full sync when going live for the first time, to pull all shop records from the source as a baseline;
2. Full sync trigger: run another full sync in the early morning every day, as a reconciliation baseline to prevent missing records at pagination boundaries;
3. Scheduling frequency: query at a high frequency during the day with */20 * * * *, to capture newly added and deactivated shops; at 23 2 * * * every night, go to the target side to trigger downstream master-data refresh.

The concrete implementation is in four steps:

1. Create a strategy in Qeasy and bind source/target platforms;
2. Configure Jushuitan interface input parameters and pagination parameters;
3. Maintain the mapping between co_id and downstream company code in the Mapping Center;
4. Trigger it manually once first, confirm the records are complete, and then enable scheduling.

Pitfall review

1. Missing records at pagination boundaries: the default page_size=100 is fine when there are few shops, but after the platform upgrades to 200 records, if page_index is not updated accordingly, data will be missed. We later unified the pagination logic at the front end in Qeasy to avoid writing scripts every time;
2. Treating co_id directly as the company code: the source-side co_id is the platform's internal number, which is often inconsistent with the ERP internal company code, and pushing it directly would cause company number confusion. The safe approach is to do a mapping at the middle layer;
3. Shops are not archived after deactivation: some fields in the source response no longer appear after a shop is deactivated, but the downstream still treats this record as an active shop, causing stock to be aggregated to a "ghost shop". This typical mistake is usually mitigated by adding a status field filter at the middle layer;
4. Target side being ignored: many people think the target side does not need to be configured when they see it is a "write null operation", but in fact Qeasy relies on this node to drive the dependencies of downstream strategies. Missing this configuration will cause the entire chain not to be triggered;
5. Scheduling time crowding together: putting the source */20 and the target 23 2 in the same time window will saturate the bandwidth. The safe approach is staggering. We are used to putting high-frequency queries during the day and low-frequency landings in the early morning.

Applicable and non-applicable scenarios

Applicable: scenarios where e-commerce platform shop records need to be aggregated into the supply chain system and will subsequently be used for sales orders or stock aggregation. Non-applicable: scenarios where shop information is only displayed on the front end and does not participate in business documents, as well as scenarios that require real-time push (second-level) change notifications — this strategy is minute-level polling, not event-driven.