Querying Sales Return Request Strategy: A Practical Guide from Kingdee to Qeasy

What This Strategy Solves

A retail client once hit a common pain point while building its supply-chain middle platform: the upstream system (Kingdee Cloud星辰 in our example) generates a large volume of sales return requests, which are the source for subsequent inbound reversals, receivable offsets, and inventory rollbacks. If these cannot be pulled back to the middle platform in a stable, timely manner, finance, warehousing, and CRM all lose data consistency. We use Qeasy (轻易云 Data Integration Platform) to carry this single query strategy, incrementally pulling sales return requests into the middle platform by time window, balancing timeliness and avoiding duplicate fetches.

Data Flow and Field Mapping

The flow is one-way pull from the source (Kingdee) to the target (Qeasy as the middle layer); it is not a write-back. The source is a QUERY endpoint; the target is a WebAPI no-op write, which means clearly: this strategy only moves data to the middle platform and writes nothing back to the source.

Key field mapping:

Two patterns we commonly see at Qeasy customers: (1) centralized code mapping — keep enum values like return reasons and return types in a single mapping table on Qeasy instead of scattering them in scripts; (2) header/body in phases — this strategy lands the header first, while a separate strategy pulls the lines, avoiding oversized single responses.

How to Configure on Qeasy

Source configuration: pick the QUERY endpoint /jdy/v2/scm/sal_in_bound_request, GET method; enable paging (use Kingdee's standard page_no / page_size); pick id as the idempotency key, with bill_no as a business-level secondary check.

Target configuration: the target is a no-op write. Its purpose is to register this pull round in the Qeasy scheduler so downstream strategies can depend on it. Keep idCheck on to avoid duplicate registrations.

Platform-side suggestion: manage these two strategies as a pair on Qeasy — the source strategy pulls data, the target strategy registers; any later strategy that actually persists header/body data should depend on this one.

Implementation Steps

Step 1 — Define the incremental start. On the first run, set create_start_time to a clear cutoff (such as the start of the month) and leave create_end_time blank so the system pages through history. Validate with a small window first (e.g., one day), then expand.

Step 2 — Trigger full backfill. On Qeasy, trigger a one-shot full pull to move historical return requests. Once the full run completes, hand over to the scheduler.

Step 3 — Set the schedule. The source strategy runs at 1-59/10 7-23 * * * — every 10 minutes during business hours, paused overnight to respect the source. The target strategy runs at 23 2 * * * for a calm daily consolidation.

Step 4 — Add monitoring and alerts. On Qeasy, attach two rules: retry on consecutive failures, and alert when a fetch returns zero rows. This ensures interface issues surface within 10 minutes.

Pitfalls Revisited

1. Data permission left off, returns from other stores leak in. We once saw return requests from unrelated stores; the cause was isdataperm defaulting to false. The safe move is to enable it explicitly and isolate by store.
2. Using bill_no as the idempotency key broke when the source renumbered a document. Use id as the primary idempotency key; treat bill_no as a business reference. This is a typical mistake.
3. Every-10-minute polling pushed the source CPU too high during peak hours. Respect the source's capacity: drop to 15-30 minutes during peak hours and only open up overnight.
4. The no-op write was mistaken for a failure. Ops engineers saw no data on the target and thought the strategy was broken. Make it clear in advance that this strategy only registers; it does not persist data.

When It Applies — and When It Does Not

Applies: when you need to incrementally pull return-request style documents from an upstream ERP/finance system into a middle platform by time window, with downstream processing. Does not apply: when you need to write back to the source (e.g., approve or reject), or when document volume is huge and demands streaming — in those cases, use a dedicated persistence strategy instead of a no-op write as a placeholder.