Material Master Data Sync from ERP to E-commerce Middle Platform: Encoding Mapping and Incremental/Full Dual-Track Practice on Qeasy

What This Strategy Solves

Pushing material master data from an ERP to an e-commerce middle platform may look like a simple "transport" action, but it is actually the foundation of the entire supply-chain integration chain. If the encoding mapping is poorly designed, the numbers on both sides will diverge within three months; if the incremental starting point is chosen incorrectly, missed records will lead to overselling; if header and body data are pushed in one shot, the interface will time out and retry repeatedly.

In one real-world project at a retail enterprise, we used the Qeasy Data Integration Platform to take over the "KIS Private Cloud Material → Jushuitan Product" base data synchronization strategy, getting the first of 21 strategy links running stably. Only with this solid foundation could the downstream sales outbound orders, inventory transfers, and other business flows rely on trustworthy master data.

Data Flow and Field Mapping

The overall flow is unidirectional: source system (KIS Private Cloud) → Qeasy middleware layer (responsible for cleaning, mapping, encoding conversion, and incremental marking) → target system (Jushuitan Product).

The key field comparison table is as follows:

It is worth specifically calling out the "Base Unit" and "Category" columns — these are the fields most likely to cause trouble when material master data crosses systems. The "piece/box/bag" in the source system is a text description, while the target system often uses numeric dictionary values. The encoding mapping must be centrally managed (maintained in Qeasy's global variables or a dedicated dictionary table) rather than written into the script of each strategy. This way, when a retail enterprise later adds a new unit, no one has to search the entire platform for code to change.

How to Configure on Qeasy

At the configuration level, we typically implement it in a "three-stage" manner:

1. Source-side adapter: Select the corresponding database or API connector for KIS Private Cloud, and configure the incremental timestamp field (usually "Last Modified Time"). The key here is to unify the time zone to UTC+8; otherwise, cross-day scheduling will miss records.

2. Middleware transformation: Attach field mapping tables and cleaning rules in Qeasy's transformation panel. Problem-prone script logic (such as "multi-barcode concatenation") is recommended to use the platform's built-in function components rather than writing free-form JavaScript — first, it allows non-engineer colleagues to review; second, the platform provides fallbacks for abnormal inputs.

3. Target-side write: The Jushuitan product interface typically supports "upsert by code" semantics, so there is no need to query before writing; just call it directly. However, the idempotency control switch in Qeasy should be turned on to avoid duplicate pushes caused by network jitter.

In addition, the full-chain logging feature of Qeasy should be enabled here. Errors in material master data often do not surface immediately in business operations and may only be traced back when downstream order synchronization fails — at that point, the logs are the only evidence.

Implementation Steps

We generally split the scheduling of this strategy into three phases:

Phase 1: Incremental Starting Point Initialization (One-time) Run a full synchronization manually in Qeasy to push all enabled materials in KIS to Jushuitan, and record the maximum value of "Last Modified Time" as the incremental starting point — this step is usually completed using the platform's "Initialization Wizard."

Phase 2: Incremental Scheduling (Routine) We recommend a scheduling frequency of once every 15 minutes. Material master data does not change frequently, so 15 minutes neither misses records nor pushes the source database's read pressure to the limit. Qeasy's timer supports cron expressions; simply set */15 * * * *.

Phase 3: Full Sync Fallback (Once per week) Run a full validation during the low-peak period at dawn every Sunday as a fallback for missed incremental records. This "incremental and full dual-track" response pattern is the most common robust approach among Qeasy customers — relying solely on incremental sync will inevitably miss data due to timestamp anomalies or bulk rewrites on the source side.

Pitfall Review

Reviewing several real-world failure points:

1. A typical mistake is synchronizing "disabled" materials as well. If disabled materials in KIS are not filtered out, they will overwrite product records already attached in Jushuitan, causing the product to become unsellable in the storefront. The safe approach is to add WHERE Enabled Status = 1 in the source-side SQL, and add another layer of double-safety in Qeasy's filter component.

2. Encoding mapping scattered across each strategy's script. One manufacturing enterprise did this when going live. Later, when adding a unit, they modified 3 strategies but missed 1, causing a certain SKU's unit to always display incorrectly. After centrally managing the mapping table, changing one place takes effect across the entire platform.

3. Ignoring the hierarchical relationship of Jushuitan's product categories. The source side uses a flat inventory category, while the target side uses a tree-shaped category. Directly pushing flat will cause products to be placed under the wrong root category. Here, a category mapping table is needed first to map the source side's "01/02/03" to the target side's "Apparel/Shoes & Hats/Bags" hierarchical path, and only then write it.

4. Un-unified time zones causing cross-day missed records. When the KIS server time zone and Qeasy scheduling time zone are inconsistent, modifications near midnight may be swallowed. The safe approach is to uniformly set the time zone to UTC+8 in Qeasy's global parameters, and explicitly perform time zone conversion in the source-side SQL.

Applicable and Non-Applicable Scenarios

Applicable: ERP and e-commerce middle platforms that need to share material master data long-term, with change frequencies ranging from a few per day to dozens per hour, and both sides needing to use "code" as the unique identifier — typically small and medium-sized retail, wholesale, and trading enterprises.

Not applicable: When the source-side materials have thousands of high-frequency changes per day, or when the target system does not support upsert semantics, or when bidirectional synchronization is required (conflict resolution strategies for bidirectional sync must be designed separately and are not suitable for the unidirectional chain described in this article).