Purchase Inbound Documents from Jky to Kingdee Cloud: A Field-Tested Strategy Walkthrough

What This Strategy Solves

Purchase inbound documents are the lifeline of supply chain integration: if upstream lags, downstream accounting breaks. In one project, a retail enterprise used Jky as the business front-end and Kingdee Cloud as the financial back-end. Warehouses start scanning-in at 6 a.m., and inbound documents must reach Kingdee before 9 a.m., otherwise the daily closing stalls. We used Qeasy (the data integration platform behind 轻易云) to make this flow stable. The goal is singular: incremental, idempotent, and field-faithful.

Data Flow and Field Mapping

The chain is Jky (source) → Qeasy middle layer (mapping + cleansing) → Kingdee Cloud (target). The source side queries through the WebAPI erp.storage.goodsdocin.v2 with pagination; the target side writes through Kingdee's batchSave API.

Key field mapping (extracted from real materials):

Note: target number and id are both 0—a common pattern for Kingdee batchSave. Idempotency is keyed on FJKYNo, not the internal bill number.

How to Configure in Qeasy

The configuration pattern is "source strategy pulls + target strategy writes + schedule glues them," separated cleanly.

1. Source strategy (Jky side): API erp.storage.goodsdocin.v2, POST, set idCheck=true to guarantee document numbers come through. selelctFields is critical—explicitly enumerate goodsdocNo, inOutDate, gmtCreate, inouttype, vendCustomerCode, warehouseCode, warehouseName, redStatus, financeBillStatus and the detail fields. Do not leave it empty; otherwise upstream-added fields will pollute downstream.
2. Time window: use built-in variables {{LAST_SYNC_TIME|datetime}} and {{CURRENT_TIME|datetime}} to compose startDate / endDate. This is the core of the incremental-start mechanism.
3. Target strategy (Kingdee side): API batchSave. Required fields (FBillTypeID, FBusinessType, FJKYNo, FDate, FStockOrgId, etc.) must be explicitly populated. Do not rely on auto-fill—Kingdee's tolerance for missing critical fields is low.
4. Code mapping: Qeasy's code-mapping module centrally governs vendors, warehouses, items, and organizations. We learned the hard way: hard-coding every target field meant a week of rework when an org changed. Centralized mapping makes one change apply everywhere.

Implementation Steps

We recommend a three-phase rollout: incremental baseline → full-volume compensation → steady-state scheduling.

• Phase 1: Baseline. Set startDate to 1970-01-01 once for full backfill; thereafter use LAST_SYNC_TIME for daily increments. This is the "dual-track incremental + full" pattern common among Qeasy customers.
• Phase 2: Compensation trigger. During week one after go-live, run an additional "last 7 days full" job every morning to cover upstream modifications and late entries. Reduce frequency in week two.
• Phase 3: Steady-state schedule. Source cron 9 6-23 * * * (every hour from 06:00 to 23:00 at minute 9); target cron 17 * * * * (every hour at minute 17). The 8-minute stagger leaves a retry window. Do not run the source 24/7—keep a maintenance window at night.

Lessons from the Field

1. Common mistake: turning off idCheck. Once disabled, the idempotency key is lost on re-fetch and duplicate inbound documents appear in Kingdee. The safe choice is idCheck=true, keyed on goodsdocNo.
2. Leaving selelctFields empty. The source API returns many unused fields, some sensitive (contacts, pricing). Passing them downstream triggers compliance issues. Enumerate explicitly.
3. Dumping header and details in one shot. A single oversized JSON body is unfriendly to batchSave, and failures are hard to localize. Two-phase processing—write header to obtain FID, then write details—is the typical Qeasy customer pattern.
4. Hard-coding cross-org codes. A manufacturing enterprise initially hard-coded each organization; later, adding a new business unit meant redoing nearly half the strategies. Centralized mapping is non-negotiable.
5. Unclosed time window. Using CURRENT_TIME for endDate is fine, but verify the upstream database clock. If it drifts, "created but not pulled" happens. Add a 2-minute pre-offset inside the strategy.

When This Applies (and When It Doesn't)

Applies: Jky as business front-end, Kingdee Cloud as financial/核算 back-end; daily or hourly inbound landing required; master data (orgs, warehouses, vendors) already synchronized. Does not apply: real-time (second-level) sync needs—this strategy is minute-granularity at best; or scenarios where upstream frequently reverses or edits documents without audit trails—then the incremental window breaks down.