Qeasy Cloud
Get Started

Kingdee Cloud Purchase Receipt to Jushuitan: A Single-Strategy Sync Tutorial

· 何金辉· Integration Solutions· 9 views· 4 min read
JushuitanKingdee Cloud采购入库供应链集成单策略轻易云

What This Strategy Solves

In one omnichannel retail scenario, purchase receipt data sits at a painful seam: Kingdee Cloud is the system of record for inbound quantities, costs, and suppliers, while Jushuitan drives e-commerce fulfillment and reconciliation. When the two drift apart, finance and warehouse teams burn hours reconciling line by line—and month-end turns into a nightmare. The goal of this strategy is straightforward: push Kingdee-approved purchase receipts into Jushuitan's purchase receipt API on a fixed cadence, so both sides stay aligned on document number, supplier, warehouse, and line items.

Data Flow and Field Mapping

The flow is unidirectional: Kingdee Cloud (source) → Qeasy data integration platform (middle layer) → Jushuitan (target). The middle layer does not persist data; it only handles field translation and code mapping.

Key field mapping:

Business MeaningKingdee Cloud FieldJushuitan FieldHandling
External document numberFBillNoexternal_idPassed through, used as idempotency key
Document primary keyFInStockEntry_FEntryIdidGenerated and back-filled by the platform
Document statusFDocumentStatus(internal check)Only approved documents are pushed
Receiving orgFStockOrgId_FNumberwms_co_idCode mapping
WarehouseFStockId_FNumberwms_co_idTemplate variable substitution
SupplierFSupplierId_FNumbersupplier_idCross-table lookup

A few points worth expanding: first, in the actual config wms_co_id is populated with the warehouse code, not the organization code—the middle layer must perform the "org → warehouse" semantic translation. Second, the supplier mapping uses _findCollection lookup, which means a separate supplier master-data sync must run upstream and populate a mapping table. This is the "centralized code-mapping" pattern we commonly see among Qeasy customers.

How to Configure on Qeasy

On the Qeasy data integration platform, this strategy is modeled as two metadata files—a source query and a target execution—and the platform orchestrates them into a directed acyclic graph.

Source-side configuration highlights: API is executeBillQuery (POST), FBillNo is the document number field, FInStockEntry_FEntryId is the line-item key, idCheck is enabled for incremental deduplication, and buildModel=false means the query returns only declared fields—avoiding the trap of dragging back unnecessary columns that slow the API down.

Target-side configuration highlights: API is jushuitan.purchasein.upload (POST), buildModel=true lets the platform generate the request body following the target schema; external_id is injected via the {{FBillNo}} template as an idempotency key; is_confirm is hardcoded to 0, so receipts land but are not auto-confirmed, leaving a buffer for human review; supplier_id is resolved via _findCollection cross-source lookup, translating Kingdee supplier codes into Jushuitan's internal numeric IDs.

Implementation Steps

Phase 1: Align the incremental starting point. On go-live day, record an "incremental start timestamp" on the Kingdee side. Qeasy will only pull documents modified after that timestamp with status = approved, avoiding dumping historical baggage into Jushuitan in one shot.

Phase 2: Full replay. For legacy data, manually trigger a full replay during off-peak hours. Qeasy deduplicates by document number, so overlap with the incremental window does not cause duplicates. This usually runs after 23:00.

Phase 3: Scheduling cadence. The source executeBillQuery runs 1-59/12 7-23 * * *—every 12 minutes during business hours; the target write runs */5 7-23 * * *—every 5 minutes. Source is slower than target; the middle layer's task queue naturally smooths the burst.

Phase 4: Warm up the supplier mapping table. Before this strategy goes live, run a separate "supplier master sync" strategy so the lookup table is populated. Otherwise the first batch of receipts will fail because suppliers cannot be resolved.

Lessons Learned From the Field

  1. The idempotency key is the document number, not the header ID. During initial configuration, someone used FID as the idempotency key, which made multiple lines on the same document look like independent receipts—and Jushuitan rejected them outright. The safe approach is external_id = FBillNo, with line-item keys used only for internal dedup.
  2. Do not default is_confirm to 1. Auto-confirmation removes the reconciliation buffer; if upstream data is wrong, it pollutes downstream immediately. A common pattern we see at customer sites is to keep it at 0 and let warehouse or finance staff confirm.
  3. Timeouts and caching on cross-table lookups. _findCollection can be slow on first execution when the mapping table is large, dragging down the whole pipeline. Add a local cache layer on Qeasy with a TTL of 10–30 minutes.
  4. Time zone and date format. Kingdee's FDate is a datetime string, but Jushuitan only accepts a date. This is a typical landmine. The safe approach is to explicitly truncate to YYYY-MM-DD in the middle layer—never pass the time portion through.
  5. Dependency ordering. This strategy implicitly depends on the "supplier master sync" and "warehouse mapping" strategies. Set depends_on explicitly in Qeasy's orchestration, otherwise the batch will fail with confusing logs when upstream tables are empty.

When This Applies—and When It Doesn't

Applies: single-organization retail or distribution businesses with stable supplier and warehouse mappings, handling hundreds to thousands of receipts per day. Does not apply: scenarios requiring multi-org split-and-rewrite, business that needs per-PO line-level receipt matching, or cases where Jushuitan demands real-time sub-second writes—the latter should use event-driven architecture rather than scheduled polling.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-jushuitan-kingdee-cloud-3490-ok-c5d84e27

Comments