Syncing VC Household List to Kingdee: A Practical Integration with Qeasy

What This Strategy Solves

In education-related businesses, master data such as households, students, and classes is often scattered across different systems. One education service provider uses its front-office management system as the business entry point and Kingdee Cloud as the financial and organizational master data backend. The need is to sync front-office household lists into Kingdee as 'organization records,' so that any new household created at the front office can be referenced immediately in Kingdee without manual maintenance on both sides. This strategy periodically pulls the household list automatically and creates or updates the corresponding Kingdee organization records.

Data Flow and Field Mapping

The data flow follows the typical 'Source → Middle Layer → Target' three-stage pattern:

1. Source side (front-office VC document system): Calls the GET /v3/households API to pull the household list page by page, with pagination parameters X-Page-Size=1000 and X-Page-Number=1. The fields we care about in the response are mainly id (unique household identifier) and name (household name); other fields like address_1 may also be present, but this strategy primarily consumes id and name.
2. Middle layer (Qeasy Data Integration Platform): Receives the response data and handles idCheck (idempotency key validation), field mapping, code transformation, and multi-language wrapping.
3. Target side (Kingdee Cloud): Calls the batchSave API to write the prepared organization records, with the core fields FNumber, FName, FCreateOrgId, and FUseOrgId.

Key field mapping table:

The idempotency key is id (the unique household identifier on the source side), written as FNumber. On subsequent re-pulls, deduplication is performed based on this key to avoid duplicate creation.

How to Configure in Qeasy

In the Qeasy Data Integration Platform, this strategy corresponds to one integration solution, with the source platform and target platform registered separately. Configuration highlights:

• Source platform metadata: type=QUERY, method=GET, api=/v3/households, number=name, id=id, with idCheck enabled. Put X-Page-Size and X-Page-Number as configurable items in the request headers, so pagination can be adjusted later without changing code.
• Target platform metadata: type=EXECUTE, method=POST, api=batchSave, number=id, id=id. FNumber is set to {{id}}, FName is set to a multi-language array wrapping {{name}} (1033 / 2052), and FCreateOrgId and FUseOrgId are set as constants.
• Centralized mapping management: For simple mappings like 'source code = target FNumber', we recommend maintaining them centrally in a mapping table. When additional fields such as address need to be added later, only one place needs to change.
• Batch submission: Kingdee's batchSave supports batching. In Qeasy, submit each page of 1000 records as one batch, which reduces the number of requests and makes it easier to locate the entire page when a retry is needed.

Implementation Steps

Roll out in phases for stability:

• Incremental starting point: On the first day of go-live, run one full sync to pull all current households as the initial baseline for Kingdee organization records.
• Full trigger: Since the source side does not provide a native change timestamp, a safe approach for the first go-live is to rely on a full sync as the fallback, then consider adding incrementals later (for example, adding a last_modified field on the source side, or doing a 'quasi-incremental' by id deduplication in the Qeasy middle layer).
• Scheduling frequency: The source strategy crontab is set to 1 8,12,16,20 * * * (4 times a day), and the target strategy is offset by 30 minutes to 30 8,12,16,20 * * *. This gives the source pull and target write a buffer, and prevents both sides from hitting each other's rate limits at the same time.
• Dependencies: This strategy has no dependencies and can run independently. However, if a student list sync is added later, it is recommended that the student strategy depends_on the household strategy, so that households exist before students.

Pitfalls and Lessons Learned

• Pitfall 1: Using name as the idempotency key causes duplicate households to be repeatedly created. In an early go-live, we directly used name as the idempotency key, which caused two households with the same name (but different addresses) to overwrite each other. The correct approach is to use the source-side id as the idempotency key, with FNumber directly taking {{id}}.
• Pitfall 2: FName was not wrapped with multi-language, so it looked fine in Chinese but appeared blank when switching to English. Kingdee's FName accepts a multi-language array and requires values for both 1033 and 2052 keys. Providing only Chinese will result in a blank display in multi-language books.
• Pitfall 3: Pagination was hardcoded to 1000, and data growth caused missed records. If the source returns more than 1000 records in a day, fixing X-Page-Number=1 will skip subsequent pages. A safe approach in Qeasy is to parameterize the pagination values, letting the platform automatically turn pages based on the response, rather than hardcoding the page number.
• Pitfall 4: Source and target fired simultaneously and triggered rate limiting. With crontabs too close together, the target started writing as soon as the source finished pulling, before the source had time to return the next page. A 30-minute offset is an empirical value.
• Pitfall 5: FCreateOrgId and FUseOrgId were missed. Although these fields are is_required=false, when omitted Kingdee uses the default organization, which causes households to be created under the wrong organization. This is only discovered later when reports do not match. The recommendation is to explicitly fill in the organization constants from the start.

When to Use and When Not to Use

Suitable for: Scenarios where the source side provides a read-only API and you need to periodically sync lists into ERP master data (organizations, customers, suppliers, etc.) with hour-level freshness requirements. Not suitable for: Scenarios where the source supports real-time change push (Webhook / message queue), extremely large data volumes requiring stream processing, or where the target is not Kingdee Cloud but financial documents requiring complex business validation. These scenarios need more sophisticated incremental and validation mechanisms and are not appropriate for the simple pull-and-batch pattern of this strategy.