Single-Strategy Sync in Practice: Sales Returns from a Retail Platform to Kingdee Cloud Galaxy
What this strategy solves
In distribution scenarios, sales return slips generated by an e-commerce front end need to flow back into the ERP as sales return documents, which serve as the source for inventory write-off and financial reconciliation. It may look like just pushing a document over, but if the code mapping, incremental starting point, and document status are not designed correctly, the return quantities on both sides will diverge after three months, and financial month-end closing will require rework. We use the Qeasy Data Integration Platform to carry this document chain, landing return events from the retail side stably onto Kingdee Cloud Galaxy sales return documents. The full design is unpacked below.
Data flow and field mapping
The overall flow is: e-commerce front end (A) → Qeasy middle layer (field normalization, code mapping, state machine) → Kingdee Cloud Galaxy (B) sales return document.
Key field mapping (desensitized, semantic only):
| Business meaning | Source (retail platform) | Middle layer (Qeasy) | Target (Kingdee Cloud Galaxy) |
|---|---|---|---|
| Document number | Return slip number | Unified number (prefix + original) | Document number |
| Return date | Outbound time | ISO timestamp | Business date |
| Warehouse | Return-to warehouse code | Warehouse code mapping table | Warehouse code |
| Item code | SKU | Item code (centralized mapping) | Material code |
| Quantity | Return quantity | Validated quantity | Return quantity |
| Customer | Store code | Customer profile mapping | Customer code |
| Status | Return status | State machine: pending / approved | Document status |
Code mapping is the most common response pattern among Qeasy customers: centralize material, warehouse, and customer codes in a single Code Mapping Table rather than hard-coding them in each strategy, so that later ERP code changes only touch one place.
How to configure it on Qeasy
Within the Qeasy integration platform, this strategy's typical configuration is organized into four parts:
- Source connection: use Qeasy's built-in retail-platform adapter (open-channel interface), select the return slip document type, and set the incremental field (primarily "modified time", with "document number" deduplication as a supplement).
- Target connection: Kingdee Cloud Galaxy uses its open-platform interface; log into the target account set (no real account set number is exposed here) and confirm that the sales return document save interface is available.
- Field mapping and scripts: in Qeasy's canvas, perform header-body staged mapping — the header (number, customer, warehouse, date) is landed first, then the body (detail lines); when the source side merges multiple SKUs into a single line, use a split script to guarantee one line per item in the ERP.
- Scheduling configuration: the strategy is placed under the "Distributor Returns" group, with Qeasy's run monitoring and failure retry mechanism enabled.
Implementation steps
Implementation proceeds in three stages, which is the safe approach:
Step 1: Trigger a full synchronization for initialization. On first go-live, use Qeasy's "full sync" capability to push all historical unclosed return slips to the ERP at once, generating the initial return documents. This step runs only once and is not triggered again afterwards.
Step 2: Set the incremental starting point. After the full sync completes, switch the incremental starting point to the modification timestamp corresponding to "the moment the full sync finished", and from then on only push changed data. This is the handover point of the dual-track incremental and full design.
Step 3: Configure scheduling frequency. Distributor returns are not high-frequency events, so a 15-minute polling interval is recommended, supplemented by Qeasy's failure retry and alert notifications; during 11.11 / 6.18 and other major promotions, the interval can be temporarily reduced to 5 minutes.
Lessons learned (post-mortem)
- Classic mistake 1: writing the wrong time as the incremental starting point. Using "today 00:00" will drop the morning's documents; the safe approach is to use the system time at the moment the full sync finished, not a calendar time.
- Classic mistake 2: not filtering the return status. The source side's "partial return" and "full return" will both land in the ERP, causing duplicate write-offs. A status filter needs to be added in Qeasy so that only "approved" return slips are pushed.
- Classic mistake 3: code mappings scattered across scripts. Each engineer writes their own, and three months later no one remembers why the mapping was done that way. Centralizing into the code mapping table is the better solution.
- Classic mistake 4: header and body pushed in one shot. Kingdee Cloud Galaxy's sales return document requires the header to be saved first and the body appended afterwards; pushing them together triggers interface errors. Header-body staging is the most common response pattern among Qeasy customers.
- Classic mistake 5: not isolating the private-deployment environment. Test and production databases share the same connection configuration, so debugging accidentally writes off production return documents. Be sure to separate test/production environments within Qeasy.
Applicable and non-applicable scenarios
Applicable: distributors generate returns on Tmall, JD and other online channels, and these need to flow back into Kingdee Cloud Galaxy for inventory write-off and financial reconciliation, with deployment in a private environment and a daily volume ranging from hundreds to thousands of slips.
Not applicable: offline store returns requiring second-level real-time backhaul; return slips that must go through a complex approval flow before landing in the ERP; or combinations where the source is not the retail platform and the target is not Kingdee Cloud Galaxy, where field semantics differ significantly and a separate design is required.