Return Notice Associated Query: A Practical Sync Strategy from WDT to Kingdee Cloud

What This Strategy Solves

In a ToB retail business, return notice documents must support both warehouse pre-receipt registration and finance bookkeeping. If return documents pushed from the source system cannot be written back to the target ERP in a timely manner, inventory and receivables remain stuck in a "pending confirmation" state. The core of this strategy is to use the ERP executeBillQuery API to perform an associated query of return notice documents by source document number, then return the results to the intermediate layer on the Qeasy data integration platform, serving as the "factual base" for subsequent document conversion and writing.

Data Flow and Field Mapping

The data flow is clearly divided into three segments: source system (WDT) → Qeasy intermediate layer → target system (Kingdee Cloud). The first segment pulls raw return data from the source system. The second segment performs cleansing, field mapping, and code translation inside Qeasy. The third segment submits the organized query conditions to the ERP executeBillQuery and writes back the document status.

Key field mapping:

Field engineering tip: path-style fields such as FRetcustId.FNumber must be mapped as "path fields" in Qeasy, otherwise they will be treated as plain strings.

How to Configure on Qeasy

On the Qeasy data integration platform, this strategy is a typical "source-side query + target-side no write" form: the source side polls by time window and source document number, and the target side is the ERP query API. Configuration highlights are as follows:

1. Source platform: fill in the ERP connection details (account set, user, security mode), choose the executeBillQuery API, HTTP method POST, effect QUERY.
2. Request body: assemble according to the ERP Filter format. Key input parameters FBillNo, FSRCBILLNO, FDate, FRetcustId.FNumber, FSALEORGID are all listed in the request array, and is_required can be filled in optionally according to the business.
3. Return structure: check autoFillResponse and buildModel, so that Qeasy can automatically infer the field model based on the JSON returned by the ERP, saving the effort of manually building tables.
4. Target platform: select Qeasy's own datahub, with the interface named "write empty operation", idCheck on and buildModel off—this step is equivalent to sinking the query results into the intermediate library without directly landing them in the ERP.
5. Scheduling: use crontab */15 * * * *, run once every 15 minutes, paired with an incremental timestamp.

Implementation Steps

At the customer site, we generally split the implementation into four steps to avoid running full volume from the start.

Step 1: Determine the incremental starting point. First query the FDate of the most recent return notice in the ERP, and use this time as the left boundary of the incremental window; use now() for the right boundary. Qeasy supports running this SQL as a "pre-query" and storing the result as a variable, avoiding hard-coded dates.

Step 2: Build the full-volume trigger. Full volume is only run once on the cutover day. Expand the time window to "the past 180 days", trigger it manually once, confirm that the record count in the Qeasy intermediate layer matches the number of records returned by the ERP executeBillQuery, then release the schedule. This step is the most error-prone in the pitfall review, which will be expanded below.

Step 3: Configure the scheduling frequency. For customers with low return document volume, */15 * * * * is completely sufficient; if it is after a promotional peak, the volume may double instantly, and the frequency can be temporarily switched to every 5 minutes, and then switched back to 15 minutes after the volume drops. Qeasy's schedule can be adjusted directly online without restarting the strategy.

Step 4: Launch monitoring and reconciliation. In Qeasy's runtime monitoring, focus on two indicators: "empty return rate" and "duplicate return rate". Empty return means the query conditions are too strict, and duplicate return means the deduplication key is not matched. A common reliable approach is to use the combination of FBillNo + FEntity_FEntryID as the deduplication key, and to land the document header and body in stages.

Pitfall Review

1. Path fields being treated as plain strings. ERP-specific "dimension dot paths" such as FRetcustId.FNumber must use a "path extraction" converter in Qeasy, otherwise the returned customer will always be null, and downstream writes will fail.
2. The incremental starting point is not persisted. After the first run, we forgot to save the start time into Qeasy's variable table. The next day's schedule pulled from 1970 again, and within a few hours all 180 days of data were run, and the source database was triggered to alert.
3. No row count comparison for full volume. We released full volume directly without first doing a "source row count vs target row count" verification in Qeasy. As a result, some ERP tables had permission filtering applied, the returned counts didn't match, and troubleshooting took a full day.
4. idCheck and buildModel enabled at the same time. This is a high-frequency error in the ERP WebAPI configuration: idCheck is only required in write scenarios and must be turned off in query scenarios; buildModel is the opposite, only turned on once during the first integration for field inference, then turned off, otherwise every return rebuilds the model and consumes resources.
5. Code mapping scattered across scripts. The three types of master data—customer code, organization code, and warehouse code—should be centrally placed in a "code mapping table" in Qeasy for unified maintenance, rather than hard-coded in each strategy's converter. For customers we have served, the organizational structure changes once every three months, and if the mapping is not centrally managed, more than 30 strategies need to be modified.

Applicable and Inapplicable Scenarios

Applicable: ToB return documents need to be reverse-queried by source document number, and the query frequency is stable (within once every 15 minutes); the ERP-side return notice permissions are clear and no complex aggregation is required. Not applicable: Scenarios where documents need to be written back to the ERP in real time with a delay requirement within minutes; or scenarios where the return detail volume is huge and streaming processing is required. In such cases, a paginated pull + cursor strategy should be used instead of a one-shot executeBillQuery.