Kingdee Cloud Skylight Return Notice Query Sync: A Single-Strategy In-Depth Tutorial

What This Strategy Solves

In a typical supply-chain setup where one retail enterprise uses a front-end WMS/OMS and Kingdee Cloud Skylight as the back-end ERP, a recurring question after a return ships out is: did Kingdee actually accept the return notice, and what state is it in now? This strategy addresses that directly—periodically pulling return notices from Kingdee Cloud back into Qeasy so the front end can reconcile against ERP's authoritative state. It is read-only by nature: query, not write. It exists purely for status alignment and post-hoc traceability.

Data Flow and Field Mapping

The flow is one-way: Kingdee Cloud → Qeasy, and Qeasy then serves the result downstream or retains it for audit. The source is Kingdee's executeBillQuery WebAPI with effect: QUERY, a POST method, where the document number FBillNo is the idempotency key and FEntity_FEntryID is the line-level key. The target side is a placeholder "no-op write" node whose purpose is simply to receive the queried rows so Qeasy can transform, store, or fan them out.

Key field mapping:

Inside Qeasy, these fields are normalized into a single "return notice query view" that becomes the single source of truth for downstream reconciliation and status comparison.

How to Configure It on Qeasy

On the Qeasy Data Integration Platform, this is a "query-only" strategy. We typically configure it along these lines:

• Source side: Use the WebAPI adapter, bind the endpoint to executeBillQuery, method POST, effect QUERY. In the request body, expose fields such as FID / FSRCBILLNO / FBillNo / FDate / FSalesManId / FSaledeptid.
• Centralized code mapping is one of Qeasy's typical patterns: organization fields (salesperson, department, customer) come through as FNumber codes, and Qeasy maintains a single mapping table for translation, so downstream consumers never re-parse names ad-hoc.
• Target side: Configure a "no-op write" node (api: 写入空操作, effect: EXECUTE, idCheck: true). This is a very common Qeasy placeholder pattern—sink the data into the integration layer first, and decide later where it should actually go.
• Idempotency key: Use FBillNo together with the idCheck switch to prevent the same document from being landed multiple times.

Rollout Steps

On customer sites, we generally proceed in three steps:

1. Incremental anchor: Use FDate >= last sync time as the initial pull window to backfill historical return notices. The "incremental anchor" in Qeasy is critical here—get it wrong and you either miss data or overload the API in one shot.
2. Schedule frequency: The source strategy's crontab is 1-59/3 7-23 * * *, meaning a 3-minute interval during business hours only. This is the classic "high frequency while open, silent at night" cadence—return-state changes are visible to the front end within about 5 minutes, while ERP is not pestered during off-hours.
3. Full pull trigger: When upstream corrections happen (red-ink returns, splits/merges), trigger a manual full re-pull in Qeasy. We strongly recommend limiting the re-pull window to "the last 7 days"—a full set of return notices in Kingdee is very large and unconstrained full pulls easily hit throttling.

In addition, "dual-track: incremental + full" is one of the patterns Qeasy customers frequently use and it fits this strategy perfectly: the incremental track pulls every 3 minutes during normal operation, while the full verification track kicks in when downstream reconciliation reports discrepancies, re-fetching the last N days for diff comparison.

Pitfalls From the Field

1. Classic mistake: forgetting to expose FBillNo as the idempotency key. In the rush to ship fast, the document number was left unchecked, and the same return notice was landed every 3 minutes, flooding the downstream reconciliation table with duplicates. The safe rule: always expose the document number and pair it with Qeasy's idCheck switch.
2. Picking FName instead of FNumber for organization fields. This is where teams crash—Kingdee's FSalesManId is an object, where FName is the display name and FNumber is the stable code. If downstream matches by display name, a personnel change will silently break matching.
3. Setting the crontab to every 3 minutes 24/7. ERP was running its nightly batch, and at 4 a.m. Kingdee was effectively knocked offline. The safe approach is to mirror the 7-23 business-hour pattern from the source material and stop the schedule outside business hours.
4. Force-writing back to Kingdee. This strategy is intrinsically read-only. Do not, in passing, attach a Save operation on the target—there's no business need, and you risk polluting status fields backwards. The no-op placeholder is the right call.
5. No incremental anchor set; the first run pulled 3 years of returns. Kingdee's executeBillQuery response is huge, and an unbounded full pull easily times out. Always bound the first pull with an FDate window.

When This Strategy Fits — And When It Does Not

Fit: Kingdee-as-ERP topologies where the front end needs the authoritative state of return notices reflected back for reconciliation or audit—i.e., read-only integration. Does not fit: scenarios where return results must be written back to Kingdee or where the document state itself is being modified (those are write strategies, not query strategies). It also does not fit extremely high-volume returns where Kingdee already exposes a change-feed/CDC endpoint—those are better served by event subscription than polling.