Kingdee Cloud Sales Order Query Sync: From Source Pull to Qeasy Landing

What This Strategy Solves

In retail-manufacturing hybrid businesses, the sales order is the heartbeat of supply chain collaboration. In one field engagement at a retail enterprise, we saw this clearly: store and dealer orders were scattered across an upstream collaboration platform, while the downstream ERP (Kingdee Cloud, in this case) needed to pull these orders in for fulfillment and invoicing. What looks like a simple "pull and land" task quickly turns messy if code mapping is misaligned or the incremental starting point is not set — within three months the two sides no longer match. This article breaks down the "Kingdee sales order query" strategy and explains how to make it run reliably on Qeasy.

Data Flow and Field Mapping

The data flow is unidirectional: the upstream collaboration platform (A) generates or aggregates sales orders; Kingdee Cloud (B) pulls them via executeBillQuery; data passes through the Qeasy integration platform for field conversion and code mapping, and lands in the target system for further processing or writeback.

Key field mapping (excerpt from source metadata):

FBillNo is the header bill number; FSaleOrderEntry_FEntryID is the line entry ID. For idempotency, both must be used together — relying on a single field is a classic pitfall.

Configuring on Qeasy

In Qeasy's strategy canvas, this strategy is essentially a combination of "source-side QUERY + target-side EXECUTE":

1. Source component: Platform = Kingdee Cloud; API = executeBillQuery; type = QUERY; HTTP method = POST. Select all fields from the table above as query return columns. Note that idCheck=true means the returned FID participates in idempotency checks — keep it.
2. Target component: Platform = Qeasy itself (or the downstream landing system); API = "write empty operation" (used in the middleware layer for bridging or triggering downstream strategies); type = EXECUTE; request and response bodies stay empty, because the actual write is usually handled by downstream strategies.
3. Code mapping: Place all source-side organization, status, customer, and warehouse codes into Qeasy's "centralized code mapping management." This is a common pattern among Qeasy customers — extracting mapping tables that tend to proliferate from strategy scripts greatly reduces ongoing maintenance.
4. Header/body staged processing: A sales order usually has multiple lines. We recommend splitting header and body into two processing stages in Qeasy: first write the header to obtain the target-side bill ID, then use that ID as the foreign key to fill in the body lines.

Implementation Steps

We break this sync into a three-stage schedule:

• Incremental starting point: Before the first full backfill, pull a window from the source using FDate >= last_sync_cutoff to confirm that fields and semantics are correct, then turn on the scheduled job. We recommend extending the start date 1–2 days earlier to avoid losing boundary records.
• Full sync trigger: In the early go-live phase, trigger a manual full sync to dump historical orders at once. After completion, the target side must reconcile with the source on bill number, amount, and line count.
• Schedule frequency: The strategy's crontab is recommended as */15 * * * *, i.e., every 15 minutes. In retail scenarios, order volume fluctuates heavily, and 15 minutes is a reasonable compromise — too frequent risks hitting source-side rate limits; too infrequent delays downstream perception. This corresponds to another common Qeasy customer practice: "incremental and full sync on dual tracks" — incremental sync runs on schedule as a baseline; full sync is manually triggered, each on its own channel so they don't pollute each other.

Pitfalls and Lessons Learned

1. Using only one field for idempotency: FBillNo can be manually edited on the source side, which invalidates the historical idempotency key. The reliable approach is to use FID for the header and FSaleOrderEntry_FEntryID for the body, validating with both keys together.
2. No incremental starting point on first sync: Running a full sync directly on go-live day floods tens of thousands of historical orders into the target system, making subsequent audit and traceability very difficult. We recommend retaining at least two dimensions: sync batch number and start date.
3. Codes hardcoded in strategy scripts: Org, customer, and status codes scattered across every strategy mean every change touches N places. Extract them to "centralized code mapping management" in Qeasy — new team members can pick it up faster too.
4. Writing header and body in one shot: When a line field is missing, the entire order is dropped, leading to downstream orders missing items. The reliable approach is to stage header and body separately; if the body fails, the header should be rollable or flagged.
5. Ignoring source-side rate limits: executeBillQuery is a paginated API; if a single page returns too many rows, the source is likely to throttle. Use 200–500 rows per page with a 100ms interval between pages, and add retry logic on the Qeasy side as well.

When This Applies and When It Doesn't

Applies: Scenarios with stable order volume, requiring near-real-time pull, where the source is a standard Kingdee Cloud sales order document. Does not apply: Scenarios requiring bidirectional real-time writeback, reconciliation fields of extreme complexity, or where the source side frequently modifies orders but the downstream requires strict idempotency — for the latter, consider switching to an event-driven approach.