Syncing Kingdee Purchase Receipts to Jushuitan: A Hands-On Guide for Supply Chain Document Integration
What This Strategy Solves
In a multi-system retail environment, one client uses Kingdee Cloud as the back-office for finance and supply chain—where purchase receipts are recorded—and Jushuitan as the front-end commerce operations platform, which needs document-level visibility into landed cost and inventory. When the two sides drift apart on numbering or status, month-end reconciliation ends up "missing dozens of documents." This strategy pushes approved purchase receipts from Kingdee to Jushuitan under a unified coding and semantic convention, ensuring a one-to-one match between the two ledgers.
Data Flow and Field Mapping
The flow is unidirectional: Kingdee Cloud → Qeasy middleware → Jushuitan. The source reads approved purchase receipts from Kingdee; the target writes them into Jushuitan's purchase receipt module. The middleware is responsible for cleansing, transforming, and enriching the payload.
The table below shows how key fields look across the three layers (source, middleware, target):
| Business Meaning | Kingdee Cloud (Source) | Qeasy Middleware | Jushuitan (Target) |
|---|---|---|---|
| Document Number | FBillNo | bill_no (unified rule) | po_bill_no (external id) |
| Document Status | FDocumentStatus | status normalized to APPROVED | bill_status=approved |
| Supplier | FSupplierId | supplier_code (via mapping table) | supplier_id |
| SKU Code | FMaterialId | sku_code | sku_id |
| Warehouse | FStockId | warehouse_code | warehouse_id |
| Received Qty | FRealQty | qty (unified UoM) | in_qty |
| Receipt Date | FDate | bill_date (YYYY-MM-DD) | in_date |
| Remarks | FNote | remark | remark |
Field mapping should live centrally inside Qeasy's mapping configuration, using a three-part layout (source field, transform function, target field) for readability. The classic pitfall is master data—supplier and warehouse—where the source uses an internal ID while the target expects a code. A mapping table must be attached at the middleware layer, otherwise the document fails to land.
How to Configure in Qeasy
The pattern is a three-stage assembly: source strategy → transformer → target strategy.
Step 1: In Qeasy Data Integration, create a source strategy that calls Kingdee's purchase receipt query interface. Hard-code the filter FDocumentStatus = Approved to avoid pushing draft documents downstream. Step 2: Build a transformer that reshapes Kingdee's field schema into what the target accepts, normalizing units, dates, and booleans here. Step 3: Create a target strategy that calls Jushuitan's purchase receipt write interface, passing bill_no as the idempotency key so duplicate pushes are absorbed safely.
Two patterns we commonly see among Qeasy customers: first, manage code mappings centrally through a "mapping table" component—one table each for suppliers, warehouses, and SKUs, updated incrementally; second, roll out header and body in phases—land the headers first to validate semantics, then attach the line items, to avoid whole-document rejection when line items misalign.
Implementation Steps
We recommend a dual-track rollout: a one-time full backfill, followed by incremental scheduling.
- Incremental Anchor Initialization: Set the incremental anchor to a three-month historical window in Qeasy and run a one-shot backfill so all receipts in that range land in Jushuitan as the baseline.
- Full Trigger Validation: Manually trigger a full run in Qeasy and verify that the receipt count and amounts on the Jushuitan side match Kingdee exactly. Only after confirmation should scheduling be enabled.
- Scheduling Activation: With daily volumes in the modest range, a 15-minute incremental cadence during business hours is reasonable. Qeasy's scheduler accepts crontab expressions directly.
- Retry and Alerting: Enable Qeasy's retry mechanism—document-level failures should be retryable and skippable, while tenant-level failures should trigger alerts to the integration owner.
Lessons from the Field
Here are five typical pitfalls we hit on a real project, in plain language.
First, the source-side status filter wasn't hard-coded. Initially we forgot FDocumentStatus, so draft documents in Kingdee were pushed to Jushuitan, polluting the downstream with "received but financially unconfirmed" records. The safe approach is to hard-code the filter in the source strategy and make sure it can't be overridden by downstream config.
Second, we passed supplier IDs directly. The source emitted FSupplierId, but Jushuitan expects supplier codes, so the first batch failed entirely. We later mounted a supplier mapping table inside Qeasy's mapping component, maintaining ID↔code correspondence, and the issue went away.
Third, date format mismatch. Kingdee's FDate includes a time component; without truncation in the middleware, Jushuitan's receipt date shifted by a day, breaking reconciliation. We now force the date into YYYY-MM-DD strings in the transformer.
Fourth, no idempotency key. We didn't forward Kingdee's document number as an idempotency key, so a re-run produced duplicates on the Jushuitan side. After wiring bill_no as the external document number and configuring Qeasy's idempotency settings, reruns are clean.
Fifth, unit-of-measure mismatch. Some items in Kingdee are stored in cases while Jushuitan defaults to pieces. Without explicit UoM conversion in the middleware, received quantities inflated several-fold. UoM rules must be declared explicitly in the transformer—don't rely on the target system to paper over the gap.
When to Use and When Not To
This strategy suits retail or distribution businesses running Kingdee as the back-office and Jushuitan as the front-end, with daily volumes in the low hundreds to low thousands of receipts. It is not a good fit when the document granularity differs sharply between the two systems—for example, when Kingdee aggregates by warehouse while Jushuitan splits by SKU—or when the document state machines are fundamentally out of sync. In those cases, master-data governance has to come first; only then should document sync be attempted.