Distributor Sales Return Sync in Practice: Wangdiantong QiMenhub to Kingdee Cloud Galaxy V2
What This Strategy Solves
In a multi-channel distribution setup, a retail client's e-commerce returns first land in Wangdiantong QiMenhub, while financial reconciliation and inventory accounting live in Kingdee Cloud Galaxy V2. Because distributors are treated as independent customer entities for return accounting, any gap between the two systems leads to awkward situations where goods are returned in Wangdiantong but neither inventory nor accounting entries appear in Kingdee. This strategy takes completed refund stock-in orders from Wangdiantong and synchronizes them into Kingdee sales return inbound documents at the distributor level, letting e-commerce returns flow automatically into supply-chain and financial accounting. On customer sites we typically deliver this with the Qeasy Data Integration Platform, aiming for stable, distributor-dimension return data landing in Kingdee.
Data Flow and Field Mapping
The data flow is straightforward: Wangdiantong QiMenhub (Refund Stock-in Order) → Qeasy middleware layer → Kingdee Cloud Galaxy V2 (Sales Return Inbound).
Header field mapping:
| Source Field (Wangdiantong) | Target Field (Kingdee) | Mapping Type | Conversion Rule |
|---|---|---|---|
check_time | bill_date | TRANSFORM | Date format conversion, extract yyyy-MM-dd |
fenxiao_nick | customer_id | COLLECTION | _findCollection lookup into customer master |
order_no | bill_no | DIRECT | Direct pass-through as document number |
shop_name | remark | TRANSFORM | Concatenate 店铺名称:{{shop_name}} |
| — | IsAutoSubmitAndAudit | CONSTANT | Fixed value true |
details_list | material_entity | ARRAY | One-to-one row mapping |
Detail line mapping:
| Source Field | Target Field | Mapping Type | Notes |
|---|---|---|---|
details_list[].spec_no / goods_no | material_entity[].material_number | DIRECT | SKU to material code |
details_list[].num | material_entity[].qty | DIRECT | Returned quantity |
details_list[].price | material_entity[].price | DIRECT | Return unit price |
details_list[].total_amount | material_entity[].amount | DIRECT | Line amount |
details_list[].remark | material_entity[].comment | DIRECT | Line remark |
Configuring It in Qeasy
On the Qeasy Data Integration Platform we split this strategy into three configuration segments so we never pile every mapping into a single node:
- Source (QUERY): API
wdt.stockin.order.query.refund, POST request. The time window usesstart_time = {{LAST_SYNC_TIME}}andend_time = {{CURRENT_TIME}}. Hard-codestatusto80(completed). Pagination is driven by the platform's pagination variable. - Middleware (centralized code mapping): The
fenxiao_nick → customer_idlookup lives in a single customer master data strategy. A single_findCollection find id from <customer strategy> where name={{fenxiao_nick}}expression handles it, and any other distributor-dimension strategy can reuse the same mapping. SKU codes rely on a preceding material master sync to keep both sides aligned. - Target (EXECUTE): API
/jdy/v2/scm/sal_in_bound, POST write.IsAutoSubmitAndAuditis fixed totrue, letting Kingdee auto-submit and auto-audit to reduce manual handling.
Implementation Steps
We recommend phased rollout with an "incremental start, full-volume fallback, dual-track" scheduling pattern:
- Step 1: Incremental starting point. On first go-live, rewind
start_timeto the beginning of the business period (e.g., start of month), setend_timeto now, and run a historical incremental pass that only picks upstatus=80completed orders, keeping noisy data out of Kingdee. - Step 2: Full-volume trigger. After 1–2 stable scheduling windows, run an additional full-volume pass on demand, typically after month-cut or large-scale master data changes.
- Step 3: Scheduling cadence. We recommend
*/10 8-22 * * *, every 10 minutes during business hours. Leaving the night untouched gives the source system room for maintenance, balancing real-time needs against wasted idle runs. - Step 4: Monitoring and reconciliation. During the first week after go-live we ask the customer to spend 30 minutes a day cross-checking return document numbers, amounts, and customer names between Wangdiantong and Kingdee to confirm the code mapping is not drifting.
Lessons from the Trenches
- Going live before clarifying where
fenxiao_nickcomes from. The field is not directly visible in the source schema; it often has to be pulled from distribution orders. Without first aligning with data owners on whether it is a nickname, a real name, or a shop identifier, the lookup will return empty customer IDs in bulk. The safe approach is to sample 50 source documents before go-live and manually verify the distributor definition. - Not hard-coding
statusto 80. The source endpoint can return intermediate states like 10/20/30/60. If those pass through unchanged, dirty data such as "returns still under review" will be auto-audited in Kingdee. We strongly recommend hard-codingstatus=80at the source request layer. - Assuming SKU codes already match. Wangdiantong's
spec_norarely matches Kingdee'smaterial_numberout of the box. If the material master sync is not stable before returns start flowing, entire detail rows will fail to land. The typical mistake is "fix master data after things break." The correct order is: get material and customer masters stable first, then open up return orders. IsAutoSubmitAndAudit=trueis a double-edged sword. Auto-audit saves effort, but once a source-side data error is auto-audited, rollback is expensive. Keep it off in the first week of go-live, then enable after verification.- Syncing header and detail in one shot. If any single detail line fails, the entire document can be rejected by the target system. The safe approach is staged debugging: get the header stable first, then open up detail lines.
When to Use and When Not to
Use it for: distribution/consignment scenarios where distributors are independent customer entities, where Wangdiantong return data needs to land in Kingdee Cloud Galaxy for financial accounting and inventory write-back.
Do not use it for: single-store direct sales where the store itself is the customer, or scenarios that need real-time intermediate-state return documents; those should use a store-flavored strategy or a separate intermediate-state workflow instead.