Kingdee Cloud Xingchen Item Master Query Sync: A Practical Guide from Jushuitan to Kingdee Material Mapping

What This Strategy Solves

In retail and supply chain integration scenarios, a typical retail enterprise usually uses one system to manage front-end business (stores, e-commerce, inventory ledger) and another to handle finance and accounting back-end. Both systems need to maintain "item master data." Once codes, units, and category definitions become inconsistent, after three months the inventory reconciliation, revenue recognition, and cost accounting will all break down. This strategy aims to query the item master from the source system (Jushuitan) through Kingdee Cloud Xingchen's open API, and unify it into the target material table, serving as the "baseline data" for subsequent document synchronization.

Data Flow and Field Mapping

The overall flow is: source system (Jushuitan item master) → Qeasy Data Integration Platform (middle layer for cleansing, mapping, incremental slicing) → target system (Kingdee Cloud Xingchen material).

The key field mapping table is as follows, this is the page most frequently asked about during customer on-site work:

Business Meaning	Source Field (Jushuitan)	Middle Layer Processing	Target Field (Kingdee Cloud Xingchen)
Item Code	sku_code	Pass-through, as idempotency key	number
Item Name	sku_name	Trim spaces and special characters	name
Item Category	category_name	Code mapping: source category → target category dictionary	category_id
Base Unit	unit	Unit dictionary unification (piece/box/pack)	base_unit
Default Warehouse	warehouse	Default value fallback	stock_default
Modification Time	modify_time	Convert to millisecond timestamp, as incremental slice condition	modify_start_time / modify_end_time

The "centralized management of code mapping" here is a common pattern among Qeasy customers: put all source-target code mapping tables in the middle layer's mapping dictionary, so the business side only modifies the dictionary, not the strategy.

How to Configure on Qeasy

To configure this strategy on the Qeasy Data Integration Platform, the core is to split "query" and "write" into two actions, connected by a data flow in between.

Source Connector: Select the Kingdee Cloud Xingchen WebAPI connector, API path /jdy/v2/bd/material, method GET, set effect to QUERY. This step only queries the data back, not directly writing to the target.
Pagination and Incremental Parameters: The API supports page, page_size (default 20), and the incremental window is controlled by modify_start_time and modify_end_time. In the template we use {{LAST_SYNC_TIME}}000 and {{CURRENT_TIME}}000 to pad the second-level timestamp into milliseconds, which is a hard requirement of Kingdee Cloud Xingchen V2 API.
Detail API Fallback: In otherRequest, attach a detailAPI = /jdy/v2/bd/material_detail to supplement the extended fields not fully returned by the list API. This is the safe approach—pull the list once, supplement details twice, avoiding missing fields from a single interface.
Target-side Empty Operation Placeholder: Configure target as "write empty operation", effect=EXECUTE, idCheck=true. This step serves as a placeholder and triggers downstream strategies; the actual write to the table is done by the downstream "item information → material" write strategy, which is also a common "header-body staged" pattern among Qeasy customers.
Scheduling Time: The source crontab is set to 4 */3 * * *, triggered every 3 hours at minute 4 for incremental; the target is set to 23 2 * * *, executed at 2:23 AM daily for fallback refresh. The offset is to avoid both sides hitting the API simultaneously and competing for resources.

Implementation Steps

We divide a complete implementation into three phases:

Phase One: Incremental Starting Point Initialization At first launch, manually trigger a "full backfill" in Qeasy to pull all current items from the source system and write them to the target. This step is not automated by crontab but manually triggered by operations, with the purpose of confirming that the mapping dictionary and field lengths are all correct. After full completion, initialize LAST_SYNC_TIME to the timestamp when this execution finishes, then enter the incremental phase.

Phase Two: Incremental Sync Goes Live Run automatically per 4 */3 * * *, with each round only querying items modified in the last 3 hours. There is a detail here: Kingdee Cloud Xingchen's timestamp interface is a closed interval, so each round's modify_end_time takes "current time - 5 minutes", leaving a 5-minute buffer to prevent missing items whose source-side write transactions have not yet been committed.

Phase Three: Full Fallback and Reconciliation Run a full verification strategy at 2:23 AM daily, comparing quantities on both sides by code, triggering alerts when differences exceed the threshold. Incremental and full dual-track operation is the most mature pattern among Qeasy customers.

Lessons Learned

Wrong Timestamp Unit: Kingdee Cloud Xingchen V2 requires milliseconds, but many engineers first write seconds, and the API returns empty data directly. The safe approach is to fix the 000 suffix in the template rather than relying on runtime calculation.
Turning on Incremental Without First Running Full: Without initializing baseline data, starting LAST_SYNC_TIME results in all historical items being missed. A typical mistake is using "current time" as the starting point—always run a full first.
Code Mapping Scattered in Strategies: Some people write source-target code mapping in every strategy, and when the business adds 50 new categories, they have to modify each one. After centralizing the mapping dictionary, adding new categories only requires modifying one place.
Detail API Not Supplemented: The list API does not return images, extended attributes, and other fields, so relying solely on the list for writes leaves target fields empty for a long time. Adding a detailAPI secondary query is a step that almost all customers eventually add.
Crontab Collision on Both Sides: Source runs every 3 hours, target also runs every 3 hours, hitting the API at the same time causes source system rate limiting. Offset scheduling is basic work, but many sites don't do it.

Applicable and Non-applicable Scenarios

Applicable: Retail/distribution/manufacturing enterprises with item master volume within 100,000 level, modification frequency at "daily" level, needing to provide baseline data for subsequent document synchronization. Not applicable: Scenarios where item master daily increment exceeds 10% of total volume, source end does not expose timestamp incremental API, or business requires "second-level" real-time synchronization—the latter needs message queues rather than scheduled pulling.