Kingdee Sales Order Query Strategy in Practice: Pulling from Kingdee Cloud to Qeasy Data Integration Platform

What This Strategy Solves (Scenario and Value)

In the supply-chain integration of one retail company, the front-end fulfillment system is Wangdiantong and the back-end ERP is Kingdee Cloud (Qingjing Flagship Edition). The two systems share a single stream of sales orders. We often hit a concrete requirement: at certain points in time (month-end reconciliation, campaign post-mortem, BI extracts), we only need to pull sales orders from Kingdee in their original shape and hand them over to BI or a downstream warehouse — without immediately writing back to Wangdiantong.

This strategy does one thing only: it queries sales orders from Kingdee Cloud in paged mode over a time window and lands them on the Qeasy data integration platform as a staging point. Downstream strategies then consume them as needed. The biggest value is decoupling "query" from "write-back" — first, get the data reliably into our hands; then, decide how to use it.

Data Flow and Field Mapping (Source → Middle Layer → Target)

The source is the open API of Kingdee Cloud (Qingjing Flagship Edition). The current target node on the Qeasy platform is a "write-empty" operation (EXECUTE). In practice, it acts as a landing/staging role and can be consumed by subsequent strategies.

Key field mapping (excerpt):

Two details worth noting on coding: billno is the business document number, while id is the system record number — do not mix them. Use id for idempotent de-duplication, and use billno for business traceability.

How to Configure It on Qeasy

This is how we typically configure it on-site: register Kingdee as the source resource and "write-empty" as the target resource, then connect them with one query strategy.

Key points:

• Source: choose platform Kingdee.QJB (Kingdee Cloud Qingjing Flagship Edition). API is /kapi/v2/dtog/sm/sm_salorder/query, method POST, effect QUERY, primary key field billno, idempotent field id with idCheck enabled.
• Request body: pageSize is 500, pageNo is maintained automatically by the paginator and starts from 1 on first run. The query condition goes into the data object and is normally a "last-modified time range" filter.
• Target: choose platform datahub (Qeasy integration platform). API is "write-empty", method POST, effect EXECUTE. The purpose of this step is to land the fetched data into the staging layer for downstream consumption.
• Build model: keep buildModel=false and autoFillResponse=true on both sides. Fields are auto-completed by the platform based on response samples, which reduces first-time onboarding cost.

Implementation Steps (Phased Scheduling)

We usually roll out in three phases: stand up the skeleton first, then adjust frequency and increment start point.

1. Full-volume trigger (cold start): temporarily change crontab to a one-shot timestamp such as 1 1 1 1 1 (used only as a trigger), and run once to pull all historical orders as a baseline. During cold start, push pageSize to the API maximum to shorten the first run.
2. Switch to the increment start point: once the full run finishes, add a filter like "last-modified time > last successful cutoff time" to the data request so that only increments are pulled afterwards. Deliberately set the increment start point a few minutes later than the actual full-run completion to avoid missing or duplicating boundary orders.
3. Move the schedule to daily: the production schedule becomes 0-59/3 7-23 * * *, i.e. every 3 minutes from 07:00 to 23:59, covering business hours. The early-morning window is reserved for heavy jobs like reconciliation and material sync, not shared with this strategy.

Pitfalls and Lessons Learned

• Classic mistake #1: wrong increment start point. The trap is "use the full-run start time as the increment start point," which causes orders within the gap to be captured both by the full run and by the increment run, producing duplicates. The safe move is to record the actual full-run completion time and add a 1–2 minute offset.
• Classic mistake #2: API blip mid-pagination. We have seen pageNo around 200+ with an occasional timeout; without checkpoint resume, subsequent pages get lost silently. Turn on the paginator's auto-retry and persist the per-page processing state so an exception can resume from the interrupted page.
• Classic mistake #3: using billno as the idempotency key. billno is the business document number, but the API-level unique identifier is id. For idempotent de-duplication on Qeasy, use idCheck=true with id, not billno.
• Classic mistake #4: pulling too much and blowing up memory. pageSize=500 is already on the high side; if orders have many line items, stress-test in a staging environment first before deciding whether to drop to 200 or 100.
• Classic mistake #5: ignoring centralized encoding mapping. Even though this strategy is "query only," the moment a downstream consumer joins in, mismatched customer/warehouse/item codes surface immediately. Keep a single mapping table on Qeasy for all downstream strategies to share — don't repeat the mapping in every strategy.

When to Use It and When Not To

Use it when the strategy acts as the "data-pull entry point" of the whole supply-chain integration — reliably pulling Kingdee sales orders to a staging layer, from which other strategies dispatch to Wangdiantong, BI or a data warehouse; or for month-end reconciliation and ad-hoc extracts. Do not use it when the business needs immediate order change visibility on Wangdiantong or strong-consistency write-back — that should be a separate "Kingdee → Wangdiantong push" strategy rather than a query-only strategy with logic patches bolted on.