Return Notice Sync in Practice: Mapping Kingdee Cloud to WDT Refund Orders

What this strategy solves

A retail client runs Kingdee Cloud as the finance and supply-chain back office and WDT as the e-commerce mid-platform. In after-sales, refund-only return notices approved in Kingdee must be pushed into WDT as original refund orders, so the storefront can auto-refund and update cash flow. It looks like a single refund line item, but without unified code mapping or a clear incremental starting point, the two sides drift apart by tens of thousands of yuan after a quarter. This strategy closes that gap.

Data flow and field mapping

The flow is unidirectional: Kingdee Cloud (return notice) → Qeasy middleware → WDT (original refund order). The middleware only translates fields and substitutes codes; it does not post inventory.

Key field mapping:

Business meaning	Kingdee (source)	Middleware	WDT (target)
Document number	FBillNo	Pass-through	refund_no
Refund amount	FRefundAmount	Number → string, 2 decimals	refund_fee
Original order no.	FOrderNo	Pass-through	tid
Refund reason	FReason	Enum mapped to WDT dictionary	reason
Shop code	FShopId	Lookup via code mapping table	shop_no
Approval time	FApproveDate	Format yyyy-MM-dd HH:mm:ss	modified

Code mapping is the part most likely to go wrong on this strategy. A common pattern on real Qeasy projects is to extract shop, item, and customer codes into a dedicated mapping table that the integration flow only references, rather than hard-codes.

How to configure on Qeasy

We use the Qeasy platform to host this strategy. Typical configuration points:

Source connector: pick Kingdee Cloud and call its document query API. Filter on FDocumentStatus='C' (approved) and FBillType='refund-only'.
Target connector: pick WDT (Qimen flavor) and call its original-refund-order create API.
Centralized code mapping: keep shop, item, and customer codes in dedicated mapping tables; the flow only references them.
Header and body staged separately: this strategy carries only header refund info; line items are pushed by a sibling strategy to keep payload size manageable.
Incremental plus full sync dual track: incremental pulls on FApproveDate >= last sync time; full sync is kept as a manual repair entry.
Retry and alerting: retry three times on timeout; failures beyond that land in an alert queue for human handling.

Implementation steps

We recommend phased rollout:

Phase 1 — set the incremental watermark. Run a one-off historical backfill for the last 30 days of approved refund-only notices, then use the last successful approval time as the watermark for incremental runs.
Phase 2 — low-volume trial. Schedule every 30 minutes, scope to the last 24 hours, and verify refund-order generation and reconciliation on the WDT side.
Phase 3 — production schedule. Move cadence to every 5–10 minutes to match normal after-sales approval rhythm. Keep full sync disabled in daily use and reserve it for repair.
Phase 4 — monitoring and reconciliation. Add a daily reconciliation task that compares counts and amounts of refund-only notices on both sides; alert on any threshold breach.

Lessons learned

Mixing refund-only with return-and-refund. A typical mistake is forgetting to scope FBillType, which lets return-and-refund notices leak through and produce wrong original refund orders in WDT. The safe approach is to lock the business type in the source filter and re-assert it in the middleware.
Building shop codes by string concatenation. Some teams write shop_id + '_' + shop_name directly in the mapping script, which breaks the moment a shop name changes. Centralized code mapping is the usual answer on Qeasy engagements, and should be in place from day one.
Forgetting to set the incremental watermark before going live. Without recording the FApproveDate watermark after the first full run, the go-live day replays a batch of historical documents. Anchor the watermark to the latest successful approval time.
Time-zone mismatch between systems. Kingdee timestamps carry time zones, while WDT expects local-time strings; cross-zone clients see an 8-hour offset around midnight. Convert to yyyy-MM-dd HH:mm:ss with no zone in the middleware.
Retries duplicate successful records. WDT rejects duplicates when an original refund order already exists. Use FBillNo as an idempotency key: skip on hit, update amount only.

Fit and limits

Fit: mid-office to ERP integrations where after-sales refund results must flow back into the e-commerce system to drive automatic refunds and cash-flow updates, with refund-only and return-and-refund kept as separate flows.

Not a fit: return-and-refund scenarios that need to write physical goods back to inventory, or fund flows that require sub-second latency — this strategy runs on a minute-level cadence and should be replaced with event-driven design in those cases.