Practical Guide: Auto-Syncing Sales Returns from WMS to Kingdee
What This Strategy Solves
Sales return documents flowing back from the e-commerce front-end into finance/ERP are the most failure-prone link in a retail chain: a customer initiates a refund at the front end, but ERP doesn't see the inbound reversal for hours, leaving finance teams with mismatched quantities and amounts during reconciliation. The essence of this strategy is to pull documents from the source system by a defined convention, clean and map them in the middle layer, then push them to the target system using its inbound parameter structure—so both sides of the ledger converge.
Data Flow and Field Mapping
The overall direction is Source → Qeasy Integration Platform → Target. We use a three-stage approach: source extraction, middle-layer transformation, target write.
| Dimension | Source (E-commerce Front-End) | Middle-Layer Standardization | Target (Finance ERP) |
|---|---|---|---|
| Document No. | Platform raw refund ID | Unified prefix + source ID | Target system document No. |
| Warehouse | Warehouse code | Code mapping table | Target warehouse archive ID |
| Product | Platform SKU code | Mapped to target material code | Target material ID |
| Quantity | Return qty | Numeric cleaning (strip sign, normalize) | Positive integer |
| Amount | Total refund | Tax-included/excluded split | Target amount fields |
| Customer | Platform member ID | Member mapping table | Target customer archive |
| Time | Platform refund-completed time | UTC+8 normalization | Target business date |
Centralized code mapping is one of the common patterns among Qeasy customers. Maintaining warehouse, product, and customer mapping in a single governable dictionary allows reuse across strategies and prevents drift from multiple per-strategy implementations.
Configuring in Qeasy
We use the Qeasy data integration platform to host the entire sync flow. A typical configuration has four parts:
- Data source registration: Configure source system access credentials (public cloud; credentials managed by the platform, never landed in local files), and build a fetch view for the sales return business module.
- Target registration: Register the target system organization and ledger environment, and confirm the API and field allowlist used to write return documents.
- Field mapping: On the mapping canvas, map source fields to middle-layer standard fields, then map those standards to target inbound parameters. Code mapping tables are mounted as external dictionaries—change the dictionary, not the flow.
- Exception handling: Configure retry policy (3 retries on network jitter), idempotency keys (combine source document No. + warehouse as the unique key), and failure alerting.
We recommend staged header/body processing: land the document header (customer, warehouse, refund time, total amount) first, then handle the detail lines (per-SKU return qty and amount). When something breaks in the middle, the blast radius is smaller, and a single return document is less likely to be voided entirely.
Implementation Steps
During implementation, we split scheduling into three phases:
- Incremental start point: Before first go-live, perform a historical full-volume backfill to determine the fetch starting point for historical return documents (for example, "earliest date available in the source system" as the lower bound), to avoid omissions.
- Full-volume trigger: On go-live night, run one full-volume pass to catch up historical data; once full-volume completes, the system auto-switches to incremental mode.
- Scheduling cadence: Return business usually demands higher real-timeliness than outbound sales. We suggest polling every 10–15 minutes. Cron in Qeasy supports second-level triggers, but overly short polling amplifies source-side pressure—a safe practice is starting at 15 minutes, observing for a week, then tightening to 10 minutes.
Incremental + full-volume dual track is another common pattern: full-volume handles "catching up history," incremental handles "chasing new entries." Both live side by side in one orchestration without conflict.
Pitfalls and Lessons
Pitfall 1: Treating a minus sign as quantity. The source sometimes returns "-1" to mean one returned unit, but the target only accepts positive integers. We added a cleaning step in the middle layer to strip signs uniformly and emit logs, preventing dirty data from landing.
Pitfall 2: Code mapping scattered across strategies. One customer initially kept product mapping in strategy A and customer mapping in strategy B. Three months later, when the warehouse code changed, A and B were each edited once—producing two inconsistent versions. The classic mistake is "each strategy maintains its own copy." The safe practice is centralized code mapping—one dictionary, one change.
Pitfall 3: Writing header and body in one shot. A return document has one header plus N detail lines. If any detail line errors during a single write, the whole document rolls back, and triage gets expensive. We later switched to staged header/body—write the header first, then details—so on error, only the detail segment rolls back.
Pitfall 4: Ignoring idempotency. On network retry, the same document may be pushed twice. Always use "source document No. + warehouse" as the idempotency key—check before write on the target side—to prevent duplicate document accumulation.
Pitfall 5: Skipping the full-volume run on first go-live. Running only incremental leaves the pre-go-live backlog permanently unreconciled. The full-volume trigger step is not optional.
Applicable and Non-Applicable Scenarios
Applicable: Retail companies integrating e-commerce front-end with finance ERP, daily return volumes in the hundreds to tens of thousands, requiring T+1 daily reconciliation.
Not applicable: Scenarios with extreme return volumes (100k+ per day) requiring streaming processing, or scenarios where return business has not yet completed status closure at the source and requires manual confirmation—the latter should follow a manual sync strategy, not automatic sync.