Query-Only Strategy for Kingdee Delivery Notice: A Lightweight Sync Practice on Qeasy

What This Strategy Solves

In supply-chain integration for a retail enterprise, there is a common pain point: delivery notices have been approved in Kingdee Cloud, but downstream warehouse, WMS, and TMS systems remain out of sync. The root cause is usually not a missing pipeline, but the absence of a stable polling anchor — a component that pulls delivery notices from Kingdee on a schedule and exposes them to other strategies. This query-only strategy plays exactly that role. It does not write into any business system; it only fetches Kingdee delivery notices into Qeasy Data Integration Platform on a fixed cadence and serves as a data source for downstream reconciliation, push, and trigger flows.

Data Flow and Field Mapping

The data flow is straightforward:

Kingdee Cloud (source)  →  Qeasy middle layer (landing)  →  No-op write (placeholder trigger)

The source side is the Kingdee Cloud endpoint /kapi/v2/sm/sm_delivernotice/batchQuery, a RESTful POST interface with effect=QUERY (query only). The target side is the built-in Qeasy "no-op write" target, which only registers the pull action itself as a subscribable event anchor.

Key field mapping:

The number field maps to billno, the id field maps to id, and with idCheck=true enabled, duplicate registration of the same document under minute-level polling is effectively avoided.

How to Configure on Qeasy

The core of this strategy is wiring together two actions: the source's query capability and the target's placeholder trigger.

Source-side configuration

• Select the Kingdee Cloud adapter, endpoint /kapi/v2/sm/sm_delivernotice/batchQuery, method POST.
• Leave data empty in the request body so Kingdee returns recently approved and pending delivery notices by default. If finer filtering is needed — such as pulling only certain warehouses or time windows — push the conditions into data.
• Do not hard-code pageNo and pageSize; leave them for Qeasy to auto-paginate. pageSize=1000 is a common upper bound on the Kingdee side; larger values may trigger rate limiting.
• Map number= billno and id= id, then enable idCheck so the scheduler deduplicates by document number.

Target-side configuration

• Select the built-in "no-op write" target on Qeasy.
• This target writes nothing to any database; it only produces an execution record that downstream subscribers can hook into.
• In Qeasy's strategy orchestration, you can place this strategy upstream as "data preparation" and attach the real write strategies to its depends_on, achieving phased scheduling where headers land first and bodies follow.

Strategy orchestration and code governance

A common pattern among Qeasy customers is centralized code mapping management: maintain Kingdee's warehouse, customer, and category codes in Qeasy's mapping center, and let all strategies reference the same mapping table. This avoids the situation where, three months later, the two sides' numbers no longer match because each strategy maintained its own copy.

Implementation Steps

Bringing this strategy up from scratch typically takes four steps.

Step 1: Incremental starting point On the first run, use "time-window pull + checkpoint resume". In the Qeasy scheduler, set the source filter to "update time > last run timestamp" so the first run only pulls the last 7 days of delivery notices, avoiding a full-volume blast that takes down the API.

Step 2: Full-volume trigger Run manually only when backfilling or onboarding a new warehouse. Confirm that the Kingdee data filter uses "last N months" or a specific document number range, and execute in batches. Qeasy auto-paginates via pageNo until an empty page is returned.

Step 3: Scheduling frequency The source-side crontab is 0-59/5 7-22 * * *, meaning every 5 minutes between 07:00 and 22:00 daily. This cadence fits retail stores with dense daytime shipping and quiet nighttime. For 24-hour warehouse operations, you can shorten it to every 2 minutes — but first confirm Kingdee's API rate-limit threshold.

Step 4: The real purpose of the no-op target The target-side crontab is 1 1 1 1 1, a one-time placeholder that is never actively executed by the scheduler — it only fires when explicitly invoked by an upstream strategy. The benefit of this design is that the target's execution time and frequency are entirely driven by the source side, eliminating clock drift between the two.

Lessons from the Field

Pitfall 1: Treating "query-only" as "with write" The most common on-site mistake is when an engineer sees "no-op write" as the target and assumes it is just a placeholder, then changes it to a real downstream system. The pulled delivery notices then flood the downstream system and overwrite real business data. The safe approach: a query-only strategy does only queries, and the real downstream write is handled by a dedicated next-stage strategy, chained through Qeasy's depends_on.

Pitfall 2: Oversized pageSize triggers rate limiting Kingdee's batch-query API usually has a QPS cap. In one project, an engineer set pageSize=5000, and the first run was rejected by the Kingdee gateway. The safe approach is to keep pageSize=1000 and stretch the schedule interval to 5 minutes or more, leaving an upstream recovery window.

Pitfall 3: idCheck disabled causes duplicate triggers If idCheck=false is left on the source side, the same delivery notice will be registered multiple times under 5-minute polling, repeatedly waking downstream strategies. Enable idCheck=true and use billno as the dedup key, and the problem disappears.

Pitfall 4: crontab does not bridge across days 0-59/5 7-22 * * * covers only 15 hours of the day. If the customer also ships at night, extend the expression to 0-59/5 0-23 * * *; otherwise nighttime delivery notices will pile up and not be pulled until the next morning.

Pitfall 5: No-op target mistaken as "incomplete configuration" During audit reviews, reviewers see the "no-op write" target with no field mapping and assume the strategy was not fully configured. In reality, this is intentional — its value lies in pulling data on time, not in writing it somewhere.

When to Use and When Not to Use

Use when: in supply-chain integration, you need the upstream ERP's delivery notices to serve as a unified data source for downstream warehouse, WMS, TMS, and reconciliation systems; or you need to provide a stable, scheduled, deduplicated data-preparation anchor for other sync strategies.

Do not use when: you need to write delivery notices directly into a business database; you require real-time (second-level) response, which 5-minute polling cannot satisfy; or Kingdee has not opened the corresponding API permission or its rate limit is extremely strict.