Shop-to-Customer Master Data Sync: A Single-Strategy Walkthrough from WMS to Kingdee Cloud

What This Strategy Solves

In multi-channel retail, a "shop" in the front-end commerce platform must become a "customer record" in the back-end ERP. The coding rules and organization ownership rarely match. In one real engagement, the client wrote front-end shops directly into the ERP as customers; three months later, finance could not match receivables to the right party because shops were never properly mapped to customer master data. The shop-to-customer sync strategy addresses this consistency issue once at the integration layer.

Data Flow and Field Mapping

The flow is: source system (front-end commerce) → Qeasy integration platform (middleware) → target system (Kingdee Cloud). The middleware handles code translation, field trimming, and pagination orchestration.

A safe pattern is to keep code mappings in Qeasy's centralized mapping table instead of hard-coding them in scripts, so adjustments later do not touch the main flow.

How to Configure It in Qeasy

A typical setup in the Qeasy integration platform has three blocks: source API, target API, and scheduling policy.

On the source side, pick wdt.shop.query (POST, QUERY semantics). Pagination parameters page_no / page_size use the built-in variables {{PAGINATION_START_PAGE}} and {{PAGINATION_PAGE_SIZE}}. A page size of 40 to 50 is a good balance between response time and recovery granularity for resumable runs.

On the target side, pick batchSave (POST, EXECUTE semantics). Map shop_no into FNumber and shop_name into FName; organization fields are constants. In Qeasy, set the target primary key to id and enable idCheck so existing customer records are updated rather than duplicated — this matters a lot for incremental sync.

Attach a schedule via crontab, for example */5 8-23 * * *, which runs every five minutes during business hours.

Implementation Steps

1. Initial full load. Trigger a full run manually in Qeasy to write all source shops into the target system as customer records. Validate on a test book first.
2. Incremental anchor. Use the last modification timestamp or the maximum shop number from the full load as the incremental starting point. Shop master data changes infrequently, but account renames and shop transfers are sensitive. The safe pattern is the dual-track approach: full load plus incremental, with a low-traffic full reconciliation once a day.
3. Schedule. Run incremental every five minutes during business hours; run a full reconciliation at night and route any drift to an alert channel.
4. Exception handling. In Qeasy, retry failed target writes up to three times, then move persistent failures to a manual compensation queue to avoid piling up dirty data.

Lessons from the Field

• Pitfall 1: hard-coded organization fields. FCreateOrgId and FUseOrgId differ across target books; once hard-coded, switching books breaks everything. Extract environment-dependent constants into Qeasy environment variables rather than embedding them in mappings.
• Pitfall 2: passing shop_no straight through as the customer code. Front-end shop numbers often have dashes or CJK characters that clash with ERP coding rules. Clean and re-encode in the middleware rather than passing values through verbatim.
• Pitfall 3: forgetting whether pagination starts at 0 or 1. The docs are clear, but most field defects come from this. Even though Qeasy's built-in pagination variables work, log the request body during the first joint verification.
• Pitfall 4: duplicate creation. With idCheck off, existing customers get inserted again, and one shop ends up mapped to several customer records downstream. Enabling idCheck is the baseline.
• Pitfall 5: scheduling outside business hours. Source systems often do maintenance at night; if the sync fires then, you may pull partial data. Restrict the schedule window to 8-23 to align with business hours.

When to Use It and When Not To

Use it for multi-channel retail where each shop is a settlement entity in the ERP and the shop-to-customer one-to-one mapping must stay consistent. Do not use it for very large shop counts (hundreds of thousands) that require sub-second real-time sync, or for scenarios where a single shop must be split into multiple customers or settlement entities — those cases need a custom master data model rather than this standard strategy.