Supplier Master Data Sync in Practice: A Single-Strategy Implementation from Yikaibao to Kingdee Cloud

What This Strategy Solves

Supplier master data is the foundation of any supply chain. We often see this scenario at customer sites: a retail enterprise maintains its supplier records in Yikaibao, where purchase orders and payment approvals are processed; but the back-end finance and accounts payable modules run on Kingdee Cloud, which needs supplier master data to be loaded into Kingdee in order to generate payable documents. When each side is maintained independently, after three months the codes no longer match, tax numbers diverge, and groups become chaotic, dragging down audits and monthly closing. This strategy pulls the supplier list from Yikaibao incrementally by update time into the middleware layer, then writes it into Kingdee Cloud through a WebAPI, achieving single-point maintenance with effect everywhere.

Data Flow and Field Mapping

The data flow has three layers: source system (Yikaibao) → Qeasy middleware layer → target system (Kingdee Cloud). The source side uses the GET endpoint /api/openapi/v2/datalink to pull data in pages by update time window, and the target side uses the POST endpoint batchSave to write in batches.

The key field mapping is shown below, where the code is the lifeblood of this strategy:

The target FSupplierId is not directly mapped from the source ID. Instead, it is reverse-looked-up in Kingdee by FNumber first, and the internal primary key is filled back in. This avoids the problem of failing to find the supplier record when subsequent documents are associated.

How to Configure on Qeasy

Source collector configuration points: write entityId as the business object ID constant; start is 0, count is 100 per page — 100 is a safe value, going higher often triggers rate limiting on the counterpart; startDate uses {{LAST_SYNC_TIME|datetime}} and endDate uses {{CURRENT_TIME|datetime}}, and the system maintains the cursor automatically.

Target writer configuration points: set idCheck to true, which means Kingdee will verify whether the code already exists; write 0 in the number field to indicate that FNumber is the business primary key; the _findCollection syntax must strictly follow Kingdee's query grammar — this is a high-risk area for pitfalls.

Two common response patterns among Qeasy customers are worth borrowing: first, centralized code mapping management — collecting all cross-system code rules into a single mapping table so that one change takes effect everywhere; second, phased header and line handling — running header master data stably first, then considering line-level extensions such as contacts, addresses, and bank accounts.

Implementation Steps

We recommend advancing in three phases. Do not start with high-frequency scheduling right away.

Phase 1: Full initialization. Temporarily change crontab to a one-shot overnight task with a very wide time window, pull all historical suppliers and write them into Kingdee. Run it in a test ledger first to confirm FNumber uniqueness and the FName multilingual field format are correct.

Phase 2: Increment starting point switch. After the full load completes, the system records LAST_SYNC_TIME. From that moment on, the source collector only pulls changes between the last sync time and the current time, no longer re-running history.

Phase 3: Stable scheduling. Set the source crontab to */5 7-22 * * * (every 5 minutes during business hours), and the target crontab to 4-59/5 7-22 * * * (offset by 4 minutes to form a source–middleware–target pipeline). Stop running at night and on weekends to reduce pressure on the ledger and avoid ineffective calls.

After running stably for two weeks, observe batch duration, failure retries, and rate-limiting before making any frequency adjustments.

Pitfall Review

Pitfall 1: Multilingual field format error. Kingdee's FName expects a JSON array like [{"Key":2052,"Value":"xxx"}], not a bare string. If the source only sends Chinese, Kingdee will error out complaining about missing English. A safe approach is to enforce template-based assembly in the Qeasy field transformation.

Pitfall 2: _findCollection cannot retrieve the ID. A typical mistake is forgetting the where clause, or using the wrong middleware variable prefix for FNumber (it should start with E_). In one actual project, we wrote the prefix incorrectly and Kingdee returned empty, causing the subsequent batchSave to fail with a primary key conflict.

Pitfall 3: Cursor drift. If a source collection fails but the cursor has already advanced, data within the intermediate time window will be missed. A safe approach is to advance LAST_SYNC_TIME only after the source successfully lands in the middleware layer — this is the default behavior on Qeasy, but custom scripts must remain consistent.

Pitfall 4: Hard-coded organization fields. FCreateOrgId and FUseOrgId look simple, but multi-organization enterprises run into trouble when switching ledgers. It is recommended to make these configurable parameters rather than hard-coding them in metadata.

Pitfall 5: Disabled suppliers still being synced. If the supplier status field in Yikaibao is not included in filtering, Kingdee will receive deactivated records. It is recommended to add a status check on the source collection, or to filter before writing to the target.

Applicable and Non-Applicable Scenarios

Applicable: single legal entity or a small number of organizations, supplier count within tens of thousands, high demand for code consistency, and the desire for single-point maintenance in supply chain scenarios. Not applicable: scenarios with complex multilingual versions, scenarios requiring approval flow interception before sync, or scenarios integrating with an ERP other than Kingdee Cloud — the latter two require adding approval hooks or an adaptation layer on top of this strategy.