Practical Guide to Syncing Return Documents from Kingdee Cloud to Wangdiantong
What This Strategy Solves
In a real retail return scenario, Kingdee Cloud acts as the ERP backend that registers return notices, while Wangdiantong serves as the front-end WMS responsible for putaway and refund execution. We use the Qeasy data integration platform to bridge this gap. The strategy has one clear goal: take the Kingdee return notice and offline-persist it into Wangdiantong as a raw refund order, keeping return quantity, amount, customer code, and product code aligned at the document level so finance can reconcile.
Data Flow and Field Mapping
The overall flow is Kingdee Cloud (source) → Qeasy middleware layer → Wangdiantong Enterprise (target). The source side pulls the return notice view, then after mapping, cleansing, and default-value filling, the data is assembled to match Wangdiantong's raw refund order API structure before being written.
Key field mapping (offline persistence scenario; fields marked with * must match on both sides):
| Business Meaning | Kingdee Source Field | Wangdiantong Target Field | Handling |
|---|---|---|---|
| Document No. * | Return notice No. (FBillNo) | Raw refund No. (refund_no) | 1:1, with prefix to prevent duplication |
| Customer Code * | Customer code (FCustId.FNumber) | Shop code (shop_no) | Managed via centralized mapping table |
| Product Code * | Material code (FMaterialId.FNumber) | Goods No. (goods_no) | Managed via centralized mapping table |
| Return Qty * | Return base qty (FQty) | Refund qty (num) | 1:1, unit must be validated |
| Return Amount * | Return amount (FAmount) | Refund amount (amount) | 1:1, two decimal places |
| Warehouse | Return warehouse (FStockId.FNumber) | Warehouse No. (warehouse_no) | Mapped; throw error if missing |
| Return Reason | Return reason (FReason) | Remark (remark) | Truncated to 200 chars |
| Doc Status | Doc status (FDocumentStatus) | Process flag (flag) | Audited → 1, otherwise 0 |
Code mapping is maintained centrally in Qeasy: one code set on the source side, one on the target side, bridged by a mapping table. If either side changes a code later, you don't blow up the whole batch.
How to Configure in Qeasy
Step one: connect the source connector (against the ERP inventory org and document type) and read the return notice view. Step two: connect the target connector pointing at the raw refund order API. Step three: in the data integration platform's strategy canvas, wire the source fields, mapping table, and target fields together.
Typical configuration points:
- Filter conditions: only pick documents where
FDocumentStatus = 'Audited'andFCancelStatus = 'Not Cancelled', to avoid sending drafts or cancelled documents downstream. - Incremental cursor: use Kingdee's
FModifyDateas the cursor. First run goes full; later runs scroll by modification time. - Centralized mapping: product code, customer code, and warehouse code all go through a unified mapping table node rather than living inside every strategy.
- Header and body in stages: header lands first; body is written per document number in batches, so a single failure retries without affecting the others.
- Null handling: quantity and amount nulls throw an error immediately; remark and reason can be null.
Implementation Steps
- Full trigger. On deployment day, run a one-time full sync of all audited, non-cancelled return notices as the baseline.
- Confirm the incremental start. After the full run completes, mark the batch end time as the incremental start point inside the Qeasy scheduler configuration.
- Scheduling frequency. Returns are not as high-frequency as sales. In practice, polling every 15 minutes is enough. During the night, drop to once per hour, and run a compensation pass in the early-morning low window.
- Failure retry and alerting. Retry at the document level three times locally; persistent failures go to a dead-letter queue and trigger an alert via enterprise IM or email. Don't let one bad document block the whole batch.
- Reconciliation check. Run a daily reconciliation at 23:30, comparing amount and quantity by document number on both sides. Differences land in a diff table for manual follow-up.
Lessons Learned from the Trenches
- Forgot the cancellation check in the filter. We only checked "audited" and missed "not cancelled", so cancelled documents got pushed and Wangdiantong ended up with extra raw refund orders. The safe move is to add both conditions.
- Code mapping scattered across strategies. An early customer hard-coded mappings inside each strategy's script. When a product code changed, every related strategy had to be updated. After centralization, only one mapping table needed editing.
- Unit mismatch. Kingdee's base unit is "piece" (件) while Wangdiantong uses "unit" (个). A 1:1 push matched the quantity but with the wrong unit. You must declare in the strategy whether you push by base unit or sales unit.
- Incremental cursor wiped by the full run. After the full run finished, the cursor wasn't switched to incremental, so the same batch got pushed again. After a full run you must explicitly set the incremental start.
- Amount precision loss. Some Kingdee versions carry four decimal places on amount fields, while Wangdiantong accepts two. Direct rounding produced a few cents of total discrepancy. The fix is to call
ROUND(x,2)explicitly in the middleware layer rather than relying on the target to truncate.
When This Applies and When It Doesn't
Applies: retail or distribution scenarios where Kingdee is the finance/supply chain backend and Wangdiantong is the front-end execution system for offline return persistence; moderate document volume and non-high-frequency returns. Does not apply: the reverse sync where Wangdiantong is the master and Kingdee is the follower, or scenarios that require real-time online refunding (those should go via the online API, not offline persistence).