Inventory Loss Sync in Practice: Integrating Jushuitan to Kingdee Cloud for Stock Document Integration

What This Strategy Solves

Anyone in retail knows that after a stock count at a store or warehouse, the surplus is called an overage and the shortage is called a loss. Loss-of-stock documents need to be pushed into Kingdee Cloud for accounting and inventory adjustments. On paper, pushing Jushuitan's count results over is just an API call. In practice, on the customer site, you discover the Jushuitan count order ID and the Kingdee loss document ID are not the same coding system—the entry organization, stock direction, and adjustment quantity all need to be re-aligned. Worse, count orders get repeatedly edited—the counter saves a draft, an auditor revises it, sometimes the document is voided and rebuilt.

Our approach: use the Qeasy Data Integration Platform as the middle layer to incrementally pull count results from Jushuitan by modification time, transform them into standard loss-of-stock documents (BillType=PKD) in Kingdee Cloud, and write them in. Once this pipeline runs cleanly, the books on both sides match and the audit trail is clear.

Data Flow and Field Mapping

The overall flow is: Jushuitan (source) → Qeasy middle layer → Kingdee Cloud (target). The middle layer handles code mapping, field cleansing, time window control, and header/line assembly.

Key field mapping:

Note: Centralized code mapping is a common pattern among Qeasy customers—store-org, material code, and warehouse mapping tables are maintained in Qeasy's "Data Dictionary," looked up by key at runtime, avoiding hardcodes scattered across strategies.

Configuring on Qeasy

Source config: /open/inventory/count/query endpoint, POST request. Key inputs are modified_begin, modified_end, page_index, and page_size. The time window is auto-filled using Qeasy variables {{LAST_SYNC_TIME|datetime}} and {{CURRENT_TIME|datetime}}. The window cannot exceed 7 days (a Jushuitan hard limit—exceed it and the API errors out), so schedule frequency should be daily—don't accumulate too much.

Target config: Kingdee Cloud's batchSave endpoint, document type fixed as PKD, org fields pulled from the mapping table. Qeasy's execution node supports bundling multiple line entries into the FEntity array in one call, avoiding splitting a single loss document into multiple invocations.

For middle-layer orchestration, we use a "header-body staged" approach: stage 1 syncs only the header (document number, date, organization); stage 2 attaches the entry details. This way, a line-level issue doesn't pollute the entire document.

Implementation Steps

Step 1: Incremental starting point. Before the strategy's first run, set LAST_SYNC_TIME to midnight of a historical day (e.g., the day before go-live) so Jushuitan outputs all count orders in that range. Qeasy's "Full Pull" button can replay historical data directly.

Step 2: Full trigger. On the first sync, we recommend a manual reconciliation—check that the mapping table's store-to-org relationships are correct. On customer sites, we typically cross-check a Jushuitan count list against Kingdee stock balances.

Step 3: Scheduling frequency. Set the source crontab to 12 3 * * * (3:12 AM pull), target crontab to 23 2 * * * (2:23 AM write). Stagger the two so the source isn't still pulling when the target is writing back.

Step 4: Monitoring and alerts. Qeasy logs every call's input, output, and latency, and auto-retries on failure. We recommend separate alert channels for three failure modes: "write failed," "time window exceeded 7 days," and "count order has no details."

Pitfalls and Lessons Learned

1. Material code mapping is the #1 pitfall. Jushuitan SKUs are merchant-defined, while Kingdee Cloud material codes follow internal rules—a mapping table must exist between the two. We've seen on-site teams just push the Jushuitan SKU as the Kingdee code; it worked for two months until a new SKU appeared in a count and the system rejected it with "material not found." The safe practice is to maintain a "material mapping" dictionary in Qeasy and run periodic consistency checks between the two systems.

2. Repeated edits to count orders can be overwritten by stale data. Jushuitan allows saving then editing a count, then editing again after approval. Our first version only deduplicated by io_id and ended up with the first revision's details persisting in Kingdee while the new version never overwrote them. The typical mistake is comparing only document status, not modification time. We later switched to "for the same io_id, take the latest modification time" and added idempotency checks for already-approved documents.

3. Time window exceeding 7 days causes Jushuitan to reject the request outright. This is a hard constraint on Jushuitan's API. Once a scheduler stalled for 3 days, recovery tried to pull a 10-day window and the API errored. The safe approach is adding a "time window splitter" in Qeasy's scheduler—if the window exceeds 7 days, automatically slice it by day and loop the request.

4. Loss-of-stock quantity signs are easy to invert. Jushuitan's qty_diff is "actual minus book," negative for losses. Kingdee Cloud's loss document entry requires a negative quantity (or absolute value plus direction field, depending on version). Once the sign rule is agreed, handle it centrally in Qeasy's "field transformation" node—don't let each business team write their own script.

5. With multi-version organizations, don't only write the main org. Retail customers often have "store-warehouse-logistics center" multiple organizations. Counts run at the store level, but Kingdee books at the inventory organization level. If the mapping table only maintains one set, loss documents end up entering Org A while accounting sits in Org B—awkward. Recommend a three-segment mapping: "store → inventory org → accounting org."

Applicable and Non-Applicable Scenarios

Applicable: Retail, chain stores, and e-commerce warehousing scenarios—the typical combination of Jushuitan as the front-end count system and Kingdee Cloud as the back-end accounting system, with count business running roughly once per day for small-to-mid integrations.

Not applicable: High-volume scenarios requiring minute-level real-time sync in warehouse-distribution integration; scenarios where an intermediate ERP (e.g., Yonyou NC) already sits between Jushuitan and Kingdee; and complex scenarios where the count process involves multi-person, multi-level approval and requires a workflow engine—in the latter case, do document conversion directly on the Kingdee side.