[Query-Only] Kingdee Purchase Orders: A Single-Strategy Pull Tutorial

What This Strategy Solves

In a supply chain integration project for a retail client, we often face this requirement: the ERP on the consumer side wants to see the latest purchase orders from Kingdee Cloud Skylink in near real-time, but only needs to "read" from Kingdee—nothing should be written back. This is precisely the typical use case for a "query-only" strategy. It pulls documents out of the source system and hands them to the middle layer; downstream links decide how to use them, and no data is written back to Kingdee. It is well suited for real-time dashboards, reconciliation checks, or downstream triggers.

Data Flow and Field Mapping

The data flow is clear: Kingdee Cloud Skylink (source) → Qeasy Data Integration Platform (middle layer) → target system (here, a "write empty operation", meaning this strategy only produces data and persistence is handled by subsequent strategies).

Key field mapping:

FBillTypeID.FNumber is a common pitfall: standard purchase, subcontracting, VMI, and other document types are all distinguished by this number in Kingdee. Downstream must route based on this number and cannot simply match by name.

How to Configure on Qeasy

In the Qeasy Data Integration Platform, the "source side" of this strategy points to Kingdee Cloud and uses the executeBillQuery POST endpoint, with idCheck enabled to ensure document uniqueness. It is recommended to enable autoFillResponse to save the manual work of binding response fields.

The "target side" is configured as a WebAPI-type "write empty operation"—this is a typical "run the pipeline without persistence" placeholder in Qeasy. It allows upstream collected data to flow smoothly into the middle layer's message queue or temporary database area, where subsequent strategies consume it.

For code mapping, Qeasy supports centralized maintenance of Kingdee document type enums, organization codes, and supplier codes in mapping tables. In one real project, we entered all enumeration values of FBillTypeID.FNumber into Qeasy's mapping dictionary, and all subsequent downstream strategies referencing purchase orders query the same table, avoiding scattered maintenance.

Implementation Steps

Step 1: Determine the incremental starting point. Before the first full pull, take a snapshot of the past 30 days of purchase orders in Kingdee to confirm the API works and no fields are lost. We recommend running a separate "full debug" in the platform, persisting the response to a debug table for manual verification.

Step 2: Configure the scheduling frequency. The cron given in the source material is 0-59/5 0-4 * * *, meaning it runs every 5 minutes between 0 AM and 4 AM daily. This is a common rhythm for supply chain integration—high-frequency polling during nighttime business off-peak hours, which captures the latest orders before the next workday starts without overloading Kingdee's query API.

Step 3: Dual-track full and incremental. A typical Qeasy approach is: first deployment runs full, then switches to incremental by FBillNo or last-modified time. Full uses a one-time task; incremental uses cron. Both run in the same pipeline but with clear branches, making rollback easy.

Step 4: Monitoring and alerts. Add "consecutive empty polls", "API timeouts", and "entry count exceeding threshold" to the monitoring dashboard in Qeasy. During the first week after launch, we check it almost every day, and only relax the vigilance once it stabilizes.

Pitfall Review

1. "Write empty operation" mistaken for a bug. Many colleagues suspect the platform is broken when they first see this target-side configuration. In fact, it is a standard placeholder for "produce data only, no target database persistence"; the downstream consumer is the actual persistence point.

2. Kingdee query API has pagination limits. executeBillQuery has a cap on rows returned per call. For very large datasets, pagination must be handled at the source side—don't wait until the response returns to slice it. Kingdee's session length is also a cost.

3. FBillNo as primary key is unstable. In some scenarios, Kingdee allows document numbers to change (e.g., after un-audit and re-submission). Relying solely on FBillNo for idempotency risks missing data. The reliable approach is to use FID + FPOOrderEntry_FEntryId as a composite primary key.

4. Schedule collides with Kingdee closing. At month-end and quarter-end, Kingdee has maintenance windows for closing operations; crons running during these windows will be rejected at the API layer. Aligning the schedule with the customer's financial closing calendar is a mandatory pre-launch task.

5. Header-body staged loading. In Qeasy, we recommend splitting the purchase order header (supplier, order date, currency) and body (detail rows, material, quantity, unit price) into two separate query requests—stabilize the header first, then bring in the body—to avoid the complexity of field mapping exploding when pulling everything at once.

Applicable and Non-Applicable Scenarios

Applicable: Downstream needs real-time visibility into Kingdee purchase order status (such as reconciliation, dashboards, triggering downstream documents), and clearly does not need to write any data into Kingdee. Not applicable: Scenarios where orders need to be written back to Kingdee, transactional consistency is required, or downstream systems directly subscribing to Kingdee changes is more cost-effective than going through the middle layer.