Qeasy Cloud
Get Started

Distributor Sales Return Sync in Practice: Wangdiantong QiMenhub to Kingdee Cloud Galaxy V2

· Integration Solutions· 21 views· 4 min read
WDT金蝶云星辰销售退货同步分销商版Field Mapping轻易云Qeasy旺店通 金蝶云星辰供应链集成

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 TypeConversion Rule
check_timebill_dateTRANSFORMDate format conversion, extract yyyy-MM-dd
fenxiao_nickcustomer_idCOLLECTION_findCollection lookup into customer master
order_nobill_noDIRECTDirect pass-through as document number
shop_nameremarkTRANSFORMConcatenate 店铺名称:{{shop_name}}
—IsAutoSubmitAndAuditCONSTANTFixed value true
details_listmaterial_entityARRAYOne-to-one row mapping

Detail line mapping:

Source FieldTarget FieldMapping TypeNotes
details_list[].spec_no / goods_nomaterial_entity[].material_numberDIRECTSKU to material code
details_list[].nummaterial_entity[].qtyDIRECTReturned quantity
details_list[].pricematerial_entity[].priceDIRECTReturn unit price
details_list[].total_amountmaterial_entity[].amountDIRECTLine amount
details_list[].remarkmaterial_entity[].commentDIRECTLine 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:

  1. Source (QUERY): API wdt.stockin.order.query.refund, POST request. The time window uses start_time = {{LAST_SYNC_TIME}} and end_time = {{CURRENT_TIME}}. Hard-code status to 80 (completed). Pagination is driven by the platform's pagination variable.
  2. Middleware (centralized code mapping): The fenxiao_nick → customer_id lookup 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.
  3. Target (EXECUTE): API /jdy/v2/scm/sal_in_bound, POST write. IsAutoSubmitAndAudit is fixed to true, 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_time to the beginning of the business period (e.g., start of month), set end_time to now, and run a historical incremental pass that only picks up status=80 completed 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

  1. Going live before clarifying where fenxiao_nick comes 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.
  2. Not hard-coding status to 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-coding status=80 at the source request layer.
  3. Assuming SKU codes already match. Wangdiantong's spec_no rarely matches Kingdee's material_number out 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.
  4. IsAutoSubmitAndAudit=true is 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.
  5. 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.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-wdt-kingdee-cloud-5121-ndf9056e2-953c392e

Comments