Sales Return Sync (Post-fill Batch RK) Tutorial: Wangdiantong to Kingdee Cloud

What This Strategy Solves

In retail and distribution businesses, stores process sales returns in the e-commerce mid-platform and generate "refund stock-in orders," but the ERP side needs the batch number filled in when posting. A common requirement we see is: pulling completed refund stock-in orders from the source system every 15 minutes into the target ERP to create settleable sales return documents. On the surface it looks like a simple document sync, but it actually involves code mapping, organization conversion, incremental cursors, and post-fill batch numbers. If any one of these is poorly designed, finance reconciliation will show mismatched numbers on both sides.

Data Flow and Field Mapping

The data flow is one-way: Wangdiantong (source) → Qeasy middle layer → Kingdee Cloud (target).

The source side calls the API wdt.stockin.order.query.refund, pulling refund stock-in orders in "completed" status within a start_time/end_time window. The target side calls batchSave to write sales return documents into Kingdee Cloud.

Key field mapping:

How to Configure on Qeasy

We use the Qeasy (Qeasy) data integration platform to host this strategy. Typical configuration has four parts.

1. Source API configuration

• API: wdt.stockin.order.query.refund, POST.
• Parameter start_time uses {{LAST_SYNC_TIME|datetime}}, end_time uses {{CURRENT_TIME|datetime}}, which are default cursor variables provided by Qeasy.
• Do not pass status; the default only queries completed orders.
• Set the id field to order_no, and disable idCheck, because the same order number may appear multiple times within the incremental window — recognition relies on the time window rather than deduplication by order number.

2. Target write configuration

• API: batchSave, POST.
• Enable idCheck = true, so Kingdee deduplicates by FBillNo and avoids duplicate postings.
• For FSaleOrgId, use Qeasy's _findCollection function to map Wangdiantong's shop_no to Kingdee's sales organization internal ID. This mapping collection is best maintained centrally in Qeasy's "Code Mapping" module, not hardcoded in the strategy.

3. Field mapping and scripts

• Header fields use basic mapping; line items go into the FEntity array line by line.
• The "post-fill batch number RK" is handled in Qeasy's custom script stage: read the batch info from the source details and merge it into the target FBatchNo. This is where customers most often request customization.

4. Scheduling

• Source crontab 2-59/15 * * * *, i.e., at minutes 2, 17, 32, 47 each hour, offset from the top of the hour to avoid source system congestion.
• Target crontab 3-59/20 * * * *, every 20 minutes, starting 1 minute after the source, leaving time for fetching and transformation.

Implementation Steps

Step 1: Initialize the incremental starting point Before going live, run a one-time historical full load and set LAST_SYNC_TIME to midnight of the go-live day; after that, switch to incremental. The initialization is usually done via Qeasy's "Full Trigger" button for a one-time backfill.

Step 2: Full trigger (optional) For customers with low return volume, you can cold-start directly in incremental mode; for customers with millions of return documents, we recommend using Qeasy's full-load task to backfill the past 90 days of completed orders first, then switch to incremental.

Step 3: Daily scheduling Source pulls every 15 minutes; target writes every 20 minutes. Qeasy's task monitoring dashboard shows pulled count, written count, and failure details.

Step 4: Exception handling Qeasy puts failed documents into an "exception queue" by default. Common causes are missing sales organization mapping or non-compliant batch number format. This requires a daily inspection.

Pitfalls and Lessons Learned

1. status field not restricted, pulling lots of "in editing" orders. Although the source API defaults to completed orders only, passing status can actually pull back in-editing or pending-review orders, causing errors in the target review workflow. The safe approach is to not pass status, or pass only 80 (completed).

2. Shop code written directly as the sales organization. A typical mistake is stuffing Wangdiantong's shop_no directly into FSaleOrgId, which fails target-side validation. It must go through a mapping collection, and the mapping should be maintained uniformly by the business department.

3. Wrong timing for post-fill batch number. The batch number RK cannot be obtained until after the "refund stock-in" is completed. If the incremental cursor is based on creation time, the batch number will be empty. It is safer to use check_time (audit time) as the incremental cursor.

4. Duplicate document posting. Source-side idCheck is disabled, but target-side idCheck must be enabled; inconsistency between the two is a classic pitfall.

5. Centralized management of Qeasy's code mapping. We have seen customers write organization mappings inside a single strategy, only to have to modify every strategy when adding a new store. The stable approach is to centralize it in Qeasy's "Master Data - Code Mapping" module so all strategies reference the same mapping — change once, takes effect across the chain.

Applicable and Non-applicable Scenarios

Applicable: Retail, distribution, and e-commerce scenarios where the source system is Wangdiantong, the target is Kingdee Cloud, and you need to incrementally sync refund stock-in orders into settleable sales return documents, with "post-fill batch number" allowed.

Not applicable: Cross-entity inter-company returns (which require transfer orders instead of sales return documents), scenarios requiring real-time second-level sync (Qeasy's minimum scheduling granularity is 1 minute), and scenarios where the source system does not support time-window queries (only full polling is possible).