Sales Return Sync in Practice: Wangdiantong to Kingdee Cloud, How to Ship Other Outbound Orders Safely
What This Strategy Solves
In retail and omnichannel scenarios, return data usually lands first in the WMS, while finance and supply chain need a formal outbound document in the ERP to do costing and inventory offset. On a real project, we needed to push sales refund orders from Wangdiantong to Kingdee Cloud as "other outbound documents (category D / other)" for a retail enterprise. It looks like simple document movement, but in refund scenarios any slip in encoding, units, batches, or stock organization will quietly corrupt the book inventory. The value of this strategy is to turn WMS business events into standard ERP documents with consistent semantics, traceability, and replay-ability.
Data Flow and Field Mapping
The overall flow is: Wangdiantong (source) → Qeasy middle layer → Kingdee Cloud (target).
On the source side, sales refund orders are pulled through the wdt.wms.stockin.refund.querywithdetail API, with order_no as the document number and idempotency key. On the target side, the batchSave API of Kingdee Cloud writes the other outbound document, with the document type set to QTCKD06_SYS (the specific code for category D / other in other outbound documents, determined by the enterprise's own document archives).
Key field mapping (only the fields most prone to engineering mistakes):
| Business meaning | Wangdiantong (source) | Kingdee Cloud (target) | Notes |
|---|---|---|---|
| Document number | order_no | FBillNo | Idempotency key, injected as {{refund_no}} |
| Document type | business field | FBillTypeID | Fixed to QTCKD06_SYS, defined by archives |
| Stock organization | business field | FStockOrgId | Hard-coded or mapped per store, maintain in Qeasy |
| Pick organization | business field | FPickOrgId | Same as stock org or mapped by rule |
| Date | business field | FDate | Use {{short_date}}, normalize to date type |
| Owner type | business field | FOwnerTypeIdHead | Mapped by org relationship, see Kingdee archives |
How to Configure on Qeasy
On the Qeasy data integration platform, this strategy can be split into four configuration blocks:
- Source connector: pick the Wangdiantong flagship Qimen adapter, select API
wdt.wms.stockin.refund.querywithdetail, method POST, enableidCheck, disablebuildModel, enableautoFillResponse. Response fields are auto-filled by the platform to reduce manual modeling. - Target connector: pick the Kingdee Cloud adapter, select API
batchSave, method POST, enableidCheck. Key constants (such as FBillTypeID, stock organization code) are written directly in the target metadata. Date and document number are injected via variables. - Encoding and organization mapping: centrally maintain a "store → stock organization" mapping and a "product code → Kingdee material code" cross-reference inside Qeasy. A common pattern among Qeasy customers is to centralize encoding mappings rather than scattering them across many strategies.
- Header and body in phases: write the header first, then fill in the body via pagination or batches. Use the "middle model + segmented submit" pattern in Qeasy to keep the body payload size under control, avoiding rejections from the target system when batchSave payloads get too large.
Implementation Steps
Phased scheduling is the key to a stable sync strategy. We recommend the following rollout:
- T0 incremental start point: at first launch, pick a historical time as the incremental start point, use the time window in
paramsto pull refund orders from Wangdiantong within that window, do one bulk ingest as the baseline. - T1 full trigger: manually trigger one full backfill on Qeasy, reconcile document numbers, stock organizations, and body details on both sides; only switch to scheduled runs after everything checks out.
- T2 scheduling cadence: set the source crontab to
0-59/50 1-2 * * *(every 50 minutes, in the 1-2 AM window, off-peak); set the target crontab to23 2 * * *(aggregated write at 2:23 AM daily). - T3 dual track of incremental and full: another common Qeasy customer pattern is the dual track — incremental for timeliness, low-frequency full sync for reconciliation, to prevent missed records.
During rollout, run first on a test organization, then cut over to the production stock organization.
Field-Tested Lessons Learned
- Wrong stock organization causes an entire batch to be rejected. A typical mistake is to write the warehouse code directly into FStockOrgId. The safe approach is to maintain a "warehouse → stock organization" mapping in Qeasy, referenced uniformly by all outbound documents.
- Missing batch and validity fields trip target-side validation. Kingdee is strict on batch management. If the source does not return batch numbers, clarify with the business whether batches are enabled. Do not leave the field empty.
- Disabling idCheck causes duplicate documents. Both source and target must have
idCheckenabled — source to dedupe by order_no, target to be idempotent by FBillNo. It is on by default in Qeasy; do not turn it off casually. - Submitting an oversized body in one call.
batchSavehas a payload size limit; too many body lines will be truncated. Configure 200-500 lines per batch in Qeasy and submit in segments. - Timezone and date format. The source returns timezone-bearing timestamps. Convert them to
{{short_date}}in the middle layer before writing FDate, to avoid "yesterday's document landing in today".
When to Use and When Not to Use
Use it when: WMS and ERP are separate, retail or omnichannel business, refunds need a formal outbound document to offset inventory. Do not use it when: refunds involve red-letter invoices, cross-organization transfers, or need a dedicated sales return document instead of other outbound; or when the source refund status machine does not match the target document type and business refactoring is required first.