Query Jushuitan Shops and Write Static Mapping: A Practical Tutorial on a Single Sync Strategy

What This Strategy Solves (Scenario and Value)

In virtually every supply chain integration project, the item sync, order sync, and inventory sync strategies must answer the same question: what does an upstream store/shop code translate to in my downstream system? Without a centrally maintained mapping table, every downstream strategy ends up re-parsing the same data, and within three months the two sides inevitably drift apart. This strategy periodically pulls upstream shop master data and persists it into a static mapping table that serves as the coding dictionary for all subsequent strategies. It sits in the foundational master-data layer — seemingly trivial, but without it the entire integration chain collapses.

Data Flow and Field Mapping (Source → Middle Layer → Target)

Data flow: upstream system (Jushuitan) → Qeasy Data Integration Platform → static mapping table (mapping storage maintained on the datahub platform).

Typical field mapping table:

The dual-sided design (a_value/a_label paired with b_value/b_label) is a common pattern among Qeasy customers — coding mappings are centrally managed, and any downstream strategy can reference this pair without worrying about upstream details.

How to Configure on Qeasy

On the Qeasy Data Integration Platform, this strategy is composed of two WebAPI nodes chained together:

1. Source node: type WebAPI, endpoint /open/shops/query (queries the upstream shop list). Pagination parameter page_index defaults to 1, page_size is fixed at 100 (the upstream's per-page ceiling). idCheck is set to true, using shop_id as the idempotency key to prevent duplicate writes.
2. Target node: type WebService, endpoint AddMappingData. The source node's returned shop_id/shop_name/shop_site/co_id are injected into a_value/a_label/b_value/b_label via {{}} placeholders. The category field receives a fixed category identifier that classifies this record under "shop mapping".

Note that the source node's autoFillResponse=true automatically persists the response structure into model fields, so subsequent nodes can reference fields directly without hand-written JSON parsing scripts.

Implementation Steps (Phased Scheduling)

Step 1: Full trigger (first go-live). Manually trigger a full pull to write all current shops into the mapping table as the baseline. This must be completed before any business strategy goes live; otherwise, item and order syncs will fail immediately when they cannot find a mapping.

Step 2: Incremental starting point. After the full pull completes, record the last pull timestamp or the maximum shop_id, and switch to incremental from there. However, given that "shops" rarely change, the safe approach is to skip incremental logic entirely and rely on periodic full refresh — upstream shop counts typically range from dozens to a few hundred, so full refresh costs almost nothing while completely eliminating the "new shop missing from mapping" risk.

Step 3: Scheduling frequency. The source node's cron is recommended to run during business hours, for example 1-59/5 7-22 * * * (7 AM to 10 PM, every 5 minutes). The target node should be staggered by 2 minutes, e.g. 3-59/5 * * * *, to prevent both nodes from competing for upstream QPS at the same instant. The "header/body phased" thinking common among Qeasy customers shows up here: shops are "header-level" master data, so the refresh frequency can be low — but it must never be absent.

Step 4: Post-launch verification. After the first run completes, randomly sample 5 rows from the mapping table and manually verify that shop_name matches the upstream UI, and confirm the category classification is correct.

Lessons Learned from the Field

1. category written incorrectly or omitted, causing downstream lookups to fail. This is a typical mistake — the category ID is a seemingly random string that is easy to mistype when entered manually. The safe approach on Qeasy is to make category a "strategy-level constant" referenced uniformly by every mapping strategy, so changes propagate globally with a single edit.
2. page_size set too high and silently truncated by upstream. Upstream per-page ceilings are usually 100; setting 500 will still return 100 and break subsequent pagination logic. Always check the documentation first; do not rely on intuition.
3. Ignoring upstream "soft-deleted" shops. Some upstream systems keep returning shops that have been deactivated. Without filtering, the mapping table keeps growing. Add a filtering script after the source node to drop shops marked as inactive.
4. Schedule collisions triggering upstream rate limits. When multiple integration strategies hit upstream simultaneously, risk control kicks in. Staggered scheduling is one of the common patterns Qeasy customers use — offsetting source and target nodes by 2 minutes immediately disperses pressure.
5. Mixing full and incremental causing duplicates. Manually triggering a full pull while an incremental run is still active produces duplicates in the mapping table. idCheck=true blocks most of them, but misclassified duplicates still get persisted. Clear the table before running.

Applicable and Non-Applicable Scenarios

Applicable: supply chain integration projects where the upstream shop count is limited (dozens to a few hundred), change frequency is low, and many downstream strategies depend heavily on shop code mapping.

Not applicable: scenarios with tens of thousands of shops, near-real-time sync requirements, or upstream shops with frequently customized/extended fields — in the latter case, prefer direct real-time API calls over a static mapping table.