WMS Pre-Receipt to Kingdee Sales Return Order: A Single-Strategy Sync Tutorial

What This Strategy Solves

In an omnichannel retail business, return flows are the most common place where numbers drift apart between systems. Stores and e-commerce channels generate pre-receipt entries in the WMS, but sales return orders in Kingdee Cloud Galaxy are either missing or delayed, which holds up financial reconciliation and inventory adjustments. What we built on the Qeasy data integration platform is a stable pipeline that pushes these entries from the WMS into Kingdee, serving as the entry point for downstream inventory and receivables adjustments.

Data Flow and Field Mapping

The flow is one-way: the flagship edition of the WMS acts as the source, Kingdee Cloud Galaxy as the target, and Qeasy as the middleware layer.

A common pattern among Qeasy customers is to keep code mappings centralized in the middleware layer. Both source and target reference the intermediate codes, so when either system upgrades, only the mapping table needs updating, not the main flow.

Configuring It in Qeasy

We recommend splitting the configuration into four blocks for clarity.

The first block is source connectivity. Pre-receipt entries are pulled from the flagship WMS via its open APIs, filtered by document status so that only approved entries enter the integration flow. Drafts or canceled documents should never reach the target.

The second block is field mapping. This step is the most underestimated. Keep header and line-level fields in separate stages: header holds document-level fields (date, customer, warehouse), while line items hold product-level fields. Separating them keeps the blast radius small when fields change and makes troubleshooting easier.

The third block is scripts and transformations. Any handling of amounts, tax rates, or unit conversions should live in a single Python script node rather than scattered across mapping configs. Typical tasks include converting between tax-inclusive and tax-exclusive prices, normalizing decimal precision, and applying fallback values for fields that the source may leave blank but the target requires.

The fourth block is target write-back. The Kingdee Cloud Galaxy side uses its sales return order API to write data. After a successful response, the integration writes back a correlation record on the Qeasy side for traceability and replay.

Implementation Steps

We usually proceed in the following order.

Step one, define the incremental boundary. Use the deployment day as the cutover: historical data goes through a one-time full sync, and same-day-and-after documents go incremental. For incremental detection, combine the last-updated timestamp with the document number to avoid relying solely on a time window, which can miss records.

Step two, trigger the full sync. Pull historical pre-receipt entries in batches based on document date, ideally a few hundred to about a thousand per batch, to stay below the concurrency limits on the Kingdee side.

Step three, configure scheduling. Return documents are usually more time-sensitive than sales orders, so a 5–10 minute interval is appropriate. The crontab expression can be set directly on the Qeasy platform without building a separate scheduler.

Step four, gray release and cutover. Let the integration flow run empty for a few hours first, with the write-back switch to Kingdee turned off. Watch mapping outputs and exception logs on the Qeasy side only. Once fields line up, enable the write. Run incremental and full sync in parallel for a period, and close the full sync entry after it drains.

Step five, monitoring and alerting. Qeasy provides run logs and failure retry out of the box, but we recommend an additional reconciliation report on the customer side to periodically compare document counts between the two systems.

Lessons Learned

First, loose document status filtering. A typical mistake is syncing draft pre-receipt entries, which results in a flood of pending return orders on the Kingdee side. The safe approach is to apply a status whitelist at source pull, accepting only approved or equivalent terminal states.

Second, hard-coded mappings in scripts. It looks convenient, but whenever either system upgrades, the script must be retested. Keep code mappings in Qeasy's mapping table and let scripts do lookups only.

Third, amount precision loss. The WMS and Kingdee handle decimal places differently, so a direct copy can introduce rounding differences. Make decimal precision explicit in scripts (two or four places) to avoid default floating-point truncation.

Fourth, missing upstream dependencies. Kingdee sales return orders often depend on existing sales delivery orders. If a return arrives before the upstream delivery has been synced, writes will fail. Add lightweight retry with dependency hints on the Qeasy side, and avoid infinite retries.

Fifth, scheduling too aggressively. A common pattern on customer sites is setting the interval to every minute, which overwhelms the Kingdee API and impacts other business flows. Five to ten minutes is enough for return scenarios; going faster only increases conflict probability.

When This Applies and When It Does Not

Applies when the WMS is the primary fulfillment system for stores and e-commerce, and Kingdee is the financial and inventory system of record, requiring a stable return document flow with relatively standard document structures and no complex approval callbacks.

Does not apply when multi-level approval callbacks on the Kingdee side need to flow back into the WMS, or when the source document state machine is highly flexible and requires per-document custom logic. Those cases are better served by heavier BPM orchestration.