Sales Order After-Sales Return Sync: A Practical Guide from JikeYun to Kingdee Cloud Cosmic
What This Strategy Solves
In the after-sales return scenario, return orders are generated on the JikeYun side, while finance and inventory settlement need to land in Kingdee Cloud Cosmic. It looks like "pushing one document over," but a return order is tightly coupled with the original sales order. If any one of the three pieces—coding mapping, state machine, or inventory direction—is misaligned, the numbers on both sides will not reconcile over the long term. We use the Qeasy data integration platform as the middle layer to take the after-sales return order out as an independent strategy, so it does not pollute the normal outbound link and is easy to reconcile incrementally on a monthly basis.
Data Flow and Field Mapping
The overall flow is: JikeYun (source) → Qeasy integration platform (middle layer, responsible for cleansing, transformation, and field enrichment) → Kingdee Cloud Cosmic (target, writing the after-sales return order).
Key field mapping, source → middle layer → target:
| Business Meaning | JikeYun (Source) | Qeasy Middle Layer | Kingdee Cloud Cosmic (Target) |
|---|---|---|---|
| Document Number | return_no | Pass through as-is | FBillNo |
| Related Original Sales Order | src_order_no | Parse and backfill | FSourceBillNo |
| Item Code | sku_code | Converted via coding mapping table | FMaterialId.FNumber |
| Return Quantity | qty | Numeric validation, negative blocked | FQty (absolute value) |
| Warehouse | warehouse | Pass through | FStockId.FNumber |
| Customer Code | customer | Converted via mapping table | FCustomer.FNumber |
| Document Status | status | Normalized to target status | FDocumentStatus |
| Sync Timestamp | — | Generated by Qeasy | FSyncTime (custom) |
We insist on placing coding mapping in Qeasy's Mapping Center for unified maintenance rather than scattering it across each strategy. A common pattern at customer sites is to build the SKU master dictionary on the Kingdee side first, keep the raw code on the JikeYun side, and do one conversion in the middle layer. This way, when expanding to multiple stores later, you change one mapping instead of every strategy.
How to Configure in Qeasy
- Register Data Sources: Register JikeYun and Kingdee Cloud Cosmic API accounts separately under "Data Sources" in Qeasy (note: tokens and keys are only visible inside the platform, never hard-coded in strategies).
- Source Events: Subscribe to JikeYun's "after-sales return order create/update" events. Set a document-type filter to only fetch orders whose status is "approved."
- Target Action: Configure the "save and audit" action on the Kingdee Cloud Cosmic side. On failure, fall back to "save only" and log the exception.
- Mapping Script: Write field mappings in Qeasy's transformer. Coding mapping goes through the Mapping Center; numeric fields get extra validation.
- Exception Handling: Enable Qeasy's alert channel and push failure details to the ops group. Every exception record carries the source document number and the target response.
Implementation Steps
We recommend a three-phase rollout for after-sales return orders: incremental start, full backfill, and steady-state scheduling.
- Incremental Start: At first go-live, use a natural-day midnight as the cutoff. Only pull "approved" return orders after the cutoff. Once confirmed correct, then open up historical data.
- Full Backfill: During the catch-up phase, manually trigger a full rescan. Pair it with a transaction code on the Kingdee side to verify document by document, avoiding carrying over historical dirty data.
- Scheduling Frequency: In steady state, run on a dual track—5-minute polling plus event-driven triggers. The "incremental and full dual track" pattern in Qeasy is the standard configuration for most customers: polling as a safety net, events for acceleration.
We also recommend phasing header and line items separately: run the header first, verify that the document number, customer, and warehouse are correct, then open up the line items. This reduces the blast radius of any single error.
Pitfalls and Lessons Learned
- State Machine Misalignment: JikeYun's "refunded" does not equal Kingdee's "approved." You must normalize the status in the middle layer; otherwise you will end up with "money already refunded but no entry posted in Kingdee."
- Quantity Sign Confusion: Return quantities are negative on the source side, but Kingdee expects positive values on the target side. This is where things often break. The safe approach is to explicitly take the absolute value in the middle layer and add a log line.
- Distributed Coding Mapping: Each strategy maintains its own SKU mapping, and three months later the numbers do not match. Centralizing into the Mapping Center is mandatory.
- Lost Reference Links: The return order does not carry the original sales order number, so Kingdee cannot perform the red-letter reversal. The typical mistake here is syncing only the document header and skipping the reference field. Be sure to capture src_order_no on the source side.
- Duplicate Pushes: Without a proper idempotency key, network jitter causes replays and Kingdee ends up with duplicate documents. We recommend using "source document number + modification time" as the idempotency key, and enabling deduplication on the target side.
Applicable and Non-Applicable Scenarios
Applicable: multi-store retail and e-commerce retail after-sales return orders that need unified posting, where document types can be split into independent strategies for reconciliation. Not applicable: cross-organization transfer returns, complex after-sales scenarios requiring partial exchange, or transition periods where the source-side state machine is not yet stable.