Practical Tutorial on the Kingdee Receiving Notice Query Strategy: End-to-End Path from Source System Pull to Middleware Landing

What This Strategy Solves

In a supply chain integration scenario for a retail enterprise, the source system is Wangdiantong and the target ERP is Kingdee Cloud Galaxy. Once both sides run business operations, the receiving step in the warehouse is where things most often go wrong: the source system has issued a shipping notice, but it has no visibility into whether a receiving notice has been generated in Kingdee, nor what stage its status has reached. Our task is to use a "Query Kingdee Receiving Notice" strategy to pull the latest document status and details from Kingdee back into the middleware layer, providing a data foundation for reconciliation, bookkeeping, and exception handling. This strategy is essentially a lightweight reverse-synchronization hook; it does not directly write target business documents, but supplies the data backbone for reconciliation and status write-back.

Data Flow and Field Mapping

The data flow is unidirectional pull: Kingdee Cloud Galaxy → Qeasy Data Integration Platform (middleware) → business-side consumers. The source side calls Kingdee's executeBillQuery interface (POST), and the target side lands the data in the middleware layer.

Key field mapping table (source → middleware):

The source marks material code and receiving org as required, which is a sound design: without these two fields, the Kingdee query errors out and the entire batch fails.

How to Configure on Qeasy

When configuring this strategy on the Qeasy integration platform, the core idea is to split the "query request" and the "landing action" into two clear action blocks.

First, register Kingdee Cloud Galaxy as a data source platform and enter the authentication information per platform conventions (out of scope for this article).

Second, configure the source action executeBillQuery. In the request body, set FormId to the form ID corresponding to the receiving notice (confirm the specific ID in the customer environment), use a query semantics other than BatchSave for Operation, and pass SelectFields as needed to limit returned columns. An engineering tip here: do not be greedy with returned columns; only pull what you actually use, otherwise the response body bloats quickly as document volume grows.

Third, configure the target action /customer/add as the middleware landing action, writing to Qeasy's staging database so that downstream BI and reconciliation programs can consume via subscription. Turn on idCheck so the platform uses the id field for idempotency and avoids duplicate writes.

Fourth, manage encoding mappings centrally. We have seen many Qeasy customers maintain "material code, org code, customer code" all in one central mapping table. When a source-side code changes, only one place needs updating, and all downstream references refresh automatically—saving a great deal of ongoing maintenance cost.

Fifth, land header and body in stages. The FBillNo row goes into the master table first, and the detail FDetailEntity_FEntryID goes into the child table, with master and child linked via document number for subsequent per-document lookup.

Implementation Steps

Phased scheduling is the key to landing this strategy successfully.

Step one, set the increment baseline. On first activation, set a clear historical lower bound for FDate in the source configuration (e.g., the 1st of a given month) and run a one-time full pull of historical receiving notices as the baseline.

Step two, trigger the full load. Manually trigger a full synchronization in Qeasy and observe the returned volume, duration, and whether the landing is correct. The initial full load typically takes minutes to tens of minutes, depending on the historical document volume.

Step three, switch to increment. Set the source-side crontab to */5 * * * *, i.e., poll every 5 minutes; the target-side landing action crontab is set to 1 1 1 1 1 and triggered on demand (the source material gives this as a placeholder, in practice driven manually or by upstream events). The increment boundary check uses FDate >= last successful time - N minutes, with N set to 5–10 minutes as an overlap window to prevent loss.

Step four, observation period. During the first 24 hours, focus on three log categories: empty responses returned from Kingdee, idempotency hit counts on Qeasy, and failed landing rows. If a given material code keeps coming back empty, go back to the mapping table and check whether the org or material master data is complete.

Pitfall Review

Pitfall 1: Using FBillNo alone as the unique key loses detail lines. The receiving notice has a header + body structure; storing only the header makes per-line reconciliation impossible. The correct approach is to split into master and child tables, with primary keys FBillNo and FDetailEntity_FEntryID respectively.

Pitfall 2: Passing material codes through without mapping. One customer stuffed Wangdiantong codes directly into Kingdee fields, but the two encoding systems did not match, and Kingdee returned empty. The safe approach is Qeasy's centralized encoding mapping, unifying the conversion before passing downstream.

Pitfall 3: Increment window set too short, causing missed documents. Kingdee's FDate is the business date, not the entry timestamp. If the increment boundary is based on entry time, backfilled documents are missed. The correct approach is to use the business date FDate as the criterion and set a 5–10 minute overlap window.

Pitfall 4: Pulling full return columns, causing a performance collapse. Pulling every field at once yields a response body of tens of MB when document volume is high, and Qeasy's parsing becomes memory-intensive. The safe approach is to tick only the necessary fields in SelectFields.

Pitfall 5: Ignoring the document status dimension. Mixing drafts, approved, and closed documents together makes downstream reconciliation impossible to interpret. The recommendation is to filter FDocumentStatus on the source side and pull only approved receiving notices, so that reconciliation is meaningful.

Applicable and Non-Applicable Scenarios

Applicable scenarios: source and target ERPs are separate, and the target-side document status needs to be pulled back for reconciliation, dashboards, or exception alerts; cross-organization receiving requires centralized visualization. Non-applicable scenarios: when the source itself is the originator of Kingdee documents, no reverse query is needed; or when downstream reconciliation frequency is below the minute level and polling the interface wastes resources.