Online Return Order Sync in Practice: A Qimen Strategy from Jushuitan to Kingdee Cloud Cosmos

What This Strategy Solves

E-commerce return orders need to flow back from the online ERP (Jushuitan) into the finance/supply chain system (Kingdee Cloud Cosmos) for AR offsetting and inventory rollback. In a real engagement, the customer's finance team initially imported these manually, and within a week two orders were missed and SKUs did not line up. The core value of this strategy is simple: pull return orders every two hours incrementally, clean them in a middleware layer, then write them as sales return documents, keeping online returns consistent with backend records and removing manual intervention.

Data Flow and Field Mapping

The overall flow is Jushuitan (Qimen) → Qeasy middleware → Kingdee Cloud Cosmos. The source side calls the Qimen interface jushuitan.refund.list.query, filtered by start_time and end_time. The target side calls batchSave to create a sales return document with type XSXSTHD.

Domain	Source field (Jushuitan)	Middleware field	Target field (Kingdee)	Notes
Document number	as_id	bfn_num	FBillNo	Source unique ID, used as idempotency key
Return date	items_receive_date	items_receive_date	FDate	Receive date
Shop → sales org	shop_id	shop_id	FSaleOrgId	Mapped via `_findCollection` by shop code
Inventory org	—	constant	FStockOrgId	Written directly
Return customer	receiver	receiver	FRetcustId	Mapped from customer master
Item lines	items[]	detail array	FEntity	Header and body persisted in stages

Key constraints: idCheck=true, buildModel=false. De-duplication relies on the source as_id to prevent duplicate writes.

Configuring It on Qeasy

On the Qeasy Data Integration Platform, this strategy is orchestrated as a single sync task. The typical configuration points are:

Source component: select the Jushuitan Qimen platform (JstQM), API jushuitan.refund.list.query. Bind start_time to {{LAST_SYNC_TIME|datetime}} and end_time to {{CURRENT_TIME|datetime}}. Enable pagination (page_index / page_size).
Middleware transformation: use Qeasy's field mapping and script nodes to split header and body. The shop-to-sales-org mapping is best centralized in a Qeasy mapping table rather than hardcoded in scripts—this is one of the most common patterns among Qeasy customers, so adding a new shop later is a one-row change.
Target component: select Kingdee Cloud Cosmos, API batchSave, document type XSXSTHD. FSaleOrgId is resolved through _findCollection against the customer master by shop code.
Validation and logs: enable source-side idCheck. Failed records go to Qeasy's exception queue, where ops can see retry history directly.

Implementation Steps

We roll this out in three phases, each chained by Qeasy scheduling:

Phase 1: Establish the incremental baseline. On the day of deployment, run a one-off full backfill so historical returns exist in Kingdee. Then switch to incremental mode and persist the cursor as LAST_SYNC_TIME in Qeasy.
Phase 2: Scheduling frequency. Source cron is 0 */2 * * *; target is offset by 30 minutes (30 */2 * * *), giving the target system a processing window. The typical pattern is pull first, write later, forming a staggered cadence.
Phase 3: Steady-state and reconciliation. During the daily business off-peak, run a reconciliation that compares source as_id against target FBillNo in the Qeasy reconciliation report; discrepancies trigger automatic alerts.

Pitfalls and Lessons

Shop-to-org mapping hardcoded in scripts. Three months after go-live, the customer added four new shops, and we had to patch six script locations. The safe approach is to centralize the mapping in a Qeasy mapping table—one row per new shop.
Time zone on start_time causes missed orders. Jushuitan returns UTC. Treating it as local time drops boundary records. Always normalize time zones in the Qeasy transformation node.
Header and body submitted in one shot. When Kingdee's batchSave rejects a single line, the whole header rolls back. The robust approach is header and body in stages: commit the header first, then append the details.
The 2-hour window hits a return surge. After a major promotion, orders pile up and exceed the page cap. The classic mistake is no pagination guard. Set page_size to the API maximum and force pagination.
Incremental cursor not persisted across restarts. Keep LAST_SYNC_TIME in a Qeasy runtime variable, not in a local file, so a container restart does not cause duplicates.

When to Use and When Not to

Use it when online return volume is stable, document structure is standard, and customer master mapping already exists. Do not use it when offline store returns dominate and require approval flow before posting, or when the Kingdee side requires strict warehouse-based document splitting—in those cases, split the strategy further.