Refund-Only Sales Return Sync from Jushuitan to Kingdee Cloud Cosmos: A Practical Walkthrough of One Strategy
What This Strategy Solves
In e-commerce retail, refunds come in two typical forms: the customer returns the goods, or the customer says "keep the goods, just refund me." The latter is very common in FMCG, apparel, and 3C categories. In Kingdee Cloud Cosmos, this usually requires a refund-only sales return document that offsets receivables and inventory while only flowing funds. Jushuitan, as the front-end transaction system, captures the original refund orders, while Kingdee Cloud Cosmos handles downstream financial accounting. Without integration between these two systems, finance teams end up reconciling return amounts manually every month, and discrepancies keep growing.
The core goal of this strategy is: push refund-only sales return documents generated in Jushuitan into the corresponding refund-only sales return documents in Kingdee Cloud Cosmos according to a defined rule, ensuring same-day posting without duplicate inventory deductions.
Data Flow and Field Mapping
The overall flow is Jushuitan → Qeasy Data Integration Platform (middleware) → Kingdee Cloud Cosmos. The middleware handles three things: fetching, cleansing, and writing.
Key field mapping (only the fields that commonly cause issues in practice):
| Business Meaning | Jushuitan (Source) | Middleware Processing | Kingdee Cloud Cosmos (Target) |
|---|---|---|---|
| Document Number | io_so_id / oids | Pass-through | FBillNo |
| Document Type | type=Return | Filter: type=Refund AND no return logistics | FBillTypeID = Sales Return (Refund-Only) |
| Refund Time | created/modified | Take modified, normalize to standard time | FDate |
| Customer Code | shop_id / co_id | Resolve via code mapping table | FCustomerID |
| Warehouse | wms_co_id | Resolve via code mapping table | FStockID |
| Item Code | sku_id | Resolve via code mapping table | FMaterialID |
| Quantity | qty | In refund-only, qty usually 0 or 1 | FQty |
| Refund Amount | refund_fee | Convert per target system tax rule | FAmount |
Header fields rely heavily on centralized code mapping management: mappings for customers, warehouses, and items must be maintained in Qeasy first, otherwise all downstream writes will fail.
How to Configure on Qeasy
The configuration focuses on three layers: strategy, mapping, and scheduling.
1. Source system access: In Qeasy, create a Jushuitan source connection and use its open API to pull refund orders (note: the filter must include "refund type = refund-only", otherwise normal returns will also be captured).
2. Target system access: Create a Kingdee Cloud Cosmos target connection, configure the organization and accounting environment (public cloud scenario uses the corresponding cloud tenant).
3. Strategy orchestration: Create a sync strategy. Source picks the Jushuitan refund-order view; target picks Kingdee sales return document (refund-only). Attach two key filters in the strategy:
- Document type = Refund
- Return logistics tracking number = empty (the core discriminator for refund-only)
4. Field mapping: Use Qeasy's mapping canvas for one-to-one header mapping. The key is translating Jushuitan's shop/customer IDs into Kingdee's FCustomerID via the code mapping table. The body usually has only one line (refund-only typically involves a single SKU with a single quantity). Force the quantity field to 0 or 1, and convert the amount field to the target system's tax-inclusive standard.
5. Write control: Enable the "Save and Approve" switch—Kingdee Cloud Cosmos documents must be approved to take effect. If the customer wants manual secondary confirmation in their process, disable it and let finance approve manually in Kingdee.
Implementation Steps
We recommend three phases to avoid issues that are hard to roll back when running full volume from the start.
Phase 1: Incremental starting point. On first run, only sync data from the day the strategy goes live to confirm documents can enter Kingdee Cloud Cosmos normally. Configure this point as the incremental timestamp in Qeasy; afterward, "modified-time-based incremental" becomes the norm.
Phase 2: Full-volume trigger. Early after go-live, run a historical full-volume task once to backfill the past N days of refund-only documents. After the full-volume task completes, switch immediately back to incremental mode. Do not run both modes in parallel, or duplicate documents will appear.
Phase 3: Scheduling frequency. In a public cloud environment, we recommend a 15-minute scheduling frequency to cover high-frequency refund scenarios on the Jushuitan side. If the customer's business volume is low, hourly is also acceptable. Qeasy's scheduler triggers automatically by cron, and the incremental starting point is automatically recorded by the platform.
Additionally, we recommend setting up a "target-system write failure auto-alert" strategy in Qeasy that pushes abnormal documents to an enterprise WeChat group, so ops can detect and intervene within 30 minutes.
Lessons Learned
Pitfall 1: Mixing "return" and "refund-only" in the same sync. Jushuitan's refund documents actually contain both return-refund and refund-only types. The field differences are small, but Kingdee Cloud Cosmos routes them to two different document types. The safe approach is to apply a hard filter at the strategy entry—"return logistics tracking number is empty"—otherwise duplicate inventory deductions or mismatched refund amounts will appear later.
Pitfall 2: Code mapping not centrally managed. If mappings for customers, warehouses, and items are scattered across every strategy in Qeasy, changing a code later means updating a dozen places. We adopted the centralized code mapping pattern: build three unified mapping tables shared by all strategies, so adding a new code only requires one edit.
Pitfall 3: Syncing header and body together causes failures. Kingdee Cloud Cosmos document writes have stricter validation on the body than the header. If the header passes but the body fails, you end up with "half-finished documents." A typical safe approach is header-body phased: write the header first to get the document inner ID, then backfill the body. Use Qeasy's "two-stage write" pattern as a whole.
Pitfall 4: Inconsistent tax-inclusive amount conventions. Jushuitan's amounts are usually tax-inclusive, but some scenarios in Kingdee Cloud Cosmos require tax-exclusive amounts. Explicit conversion must happen in the middleware—do not rely on downstream defaults, or monthly reconciliation differences will be large.
Pitfall 5: Incremental starting point reset. In Qeasy, accidentally clicking "re-initialize incremental" will cause duplicate historical data pulls. Document this clearly in the strategy spec: the incremental starting point can only be set once at initial go-live; subsequent resets are forbidden. If you really need to rerun history, run a separate full-volume task.
Suitable and Unsuitable Scenarios
Suitable: Retail/distribution enterprises with Jushuitan as the e-commerce front-end and Kingdee Cloud Cosmos as the ERP back-end; customers frequently initiate refund-only requests and expect same-day posting; finance needs to reconcile receivable offsets at the document level.
Not suitable: Customers who already have a complete return process in Kingdee Cloud Cosmos and do not wish to change it; refund processes on the Jushuitan side are fully decoupled from Kingdee and do not need inventory/receivable linkage; or business volume is extremely small (fewer than 5 orders per day), where manual export may be more cost-effective than automation.