Shop-to-Customer Master Data Sync in Practice: An Incremental Integration from Guanyi Cloud to Kingdee Cloud Xingchen

What This Strategy Solves

In e-commerce businesses, a shop is the smallest unit of a sales channel, but Kingdee Cloud Xingchen's supply chain and financial accounting rely on the Customer master data object. We often run into this in real projects: a merchant adds new online shops in the source system, yet finance can't reconcile the next day because customer records are missing or codes don't match, which in turn blocks downstream sales orders and inventory posting. Mapping Guanyi Cloud's shop entity directly to Kingdee's customer object keeps order, inventory, and reconciliation flows running smoothly.

Data Flow and Field Mapping

The end-to-end flow is Guanyi Cloud → Qeasy Data Integration Platform → Kingdee Cloud Xingchen V2, with a single middleware hop. Incremental data is fetched by a modify-time window via the source API gy.erp.shop.get, and written through the target API /jdy/v2/bd/customer.

For primary keys, the source binds number=code and id=id; the target currently uses number=1 and id=1 as placeholders. The target enables idCheck=true, which means the primary key must be validated before writing.

The source also exposes nick (shop nickname), note (remark), type_name (shop type), and create_date/modify_date as extensible fields. They are not mapped in this baseline plan but can later be wired up through COLLECTION or TRANSFORM rules.

How to Configure on Qeasy

For the Source side, choose the WebAPI adapter, set effect=QUERY, method=POST, and point the API to gy.erp.shop.get. Bind the primary key as code→number and id→id, turn on idCheck=true, and keep buildModel off. The incremental parameters use modify_start_date = {{LAST_SYNC_TIME|datetime}} and modify_end_date = {{CURRENT_TIME|datetime}}. Pagination defaults are page_no=1 and page_size=10.

For the Target side, again use the WebAPI adapter with effect=EXECUTE and the endpoint /jdy/v2/bd/customer. In the request body, set name to {{name}} and number to {{code}}. The number field is required here because Kingdee's contract states that when an encoding rule is configured and the record is being updated, number must be passed; otherwise the backend will reject the update.

A common pattern we apply on Qeasy is centralised code-mapping governance: this baseline plan only uses DIRECT mappings, but when the merchant later wants shop type → customer category mapping, you can simply add a COLLECTION rule inside the mapping editor—no need to change the API contract.

Implementation Steps

Phase 1 — Incremental Anchor. Before go-live, run a one-shot full pull on Qeasy so historical shops are migrated in a single pass; that timestamp becomes the incremental anchor. After that, the scheduler uses the rolling modify_start_date ~ modify_end_date window.

Phase 2 — Scheduling Cadence. The source crontab is */20 7-21 * * * — every 20 minutes between 07:00 and 21:00, covering the main e-commerce business window. The target crontab is 6-59/27 7-21 * * *, intentionally staggered 27 minutes from the source to prevent both sides from firing in the same minute and piling up load.

Phase 3 — Production Cutover and Monitoring. After the first successful run, inspect Qeasy's runtime logs for the actual request and response payloads and confirm that number always carries the code. If Kingdee returns an "encoding already exists" error, the root cause is duplicate codes in Guanyi Cloud's master data; the fix belongs to data governance upstream, not the integration strategy.

Lessons Learned

1. Skipping the initial full pull. Going straight into incremental mode with "now" as the anchor silently drops every historical shop. A typical mistake; the safe move is to backfill once before go-live and seed LAST_SYNC_TIME accordingly.

2. Forgetting to pass number on the target side. Kingdee's "number required when an encoding rule is in effect and the record is being updated" is a hidden rule that catches teams out. We always pass number={{code}}, even when no encoding rule is in play, to keep traceability.

3. Enabling idCheck without wiring up an id lookup. Right now, the target's id and number are placeholders (both 1), and idCheck is on but no real lookup fetches the target's actual id. The robust pattern—borrowed from the material-sync strategy—is to add a _mongoQuery lookup by number, fetch the target id, then perform the update.

4. Source and target schedules aligned, spiking both systems at once. Setting both crontabs to */20 causes both sides to fire in the same minute and crushes throughput. The 20-minute / 27-minute offset spreads the load.

5. Mapping every optional field on day one. Trying to sync nick, note, and type_name simultaneously makes the first run very hard to debug. We recommend stabilising name and number first, then expanding on the business's own rhythm.

When This Fits — and When It Doesn't

Good fit: e-commerce retailers with a manageable shop count (tens to a few thousand), stable change frequency, and a need to treat shops as customer dimensions for finance.

Not a fit: shops that are concurrently written from multiple sources (e.g., Guanyi Cloud plus an in-house ERP), or scenarios where the target requires complex mapping by customer category, hierarchy, or multi-org dimensions—DIRECT mapping cannot carry that, and you need to upgrade to a centralised code-mapping regime plus TRANSFORM expressions.