Authoritative Tutorial on Interface Field Handbook for Jushuitan & Kingdee Cloud Cosmic Supply Chain Integration
What This Interface Solves
The integration between Jushuitan (e-commerce ERP) and Kingdee Cloud Cosmic (enterprise ERP) is the core link for e-commerce retail enterprises to close the loop of "online sales—inventory linkage—financial accounting." This interface family solves three major problems: automatically syncing e-commerce sales outbound/returns to Kingdee to generate financial vouchers, flowing back purchase and inventory business from Kingdee to Jushuitan to keep inventory consistent, and keeping master data and codes unified between the two systems.
Interface Capability Overview
Authentication: Jushuitan uses AppKey+AppSecret signing; Kingdee Cloud Cosmic uses a third-party login API to exchange for a SessionToken before invoking business interfaces.
Request/Response Structure: Jushuitan interfaces are mainly JSON, supporting pagination (page_index/page_size) and time-window (modified_begin/modified_end) increments; Kingdee interfaces are based on FormId+JSON, requiring chained Operation (Save/BatchSave/Submit/Audit) calls to drive document status transitions.
Pagination/Incremental Mode: On the Jushuitan side, status+date_type increments are common (e.g., Strategy 17 uses status=Confirmed, date_type=2, 7-day window); on the Kingdee side, FApproveDate is the typical incremental anchor, and full backfills rely on the LAST_SYNC_TIME cursor.
Typical Field Mappings
| Field Name | Type | Meaning | Practical Notes |
|---|---|---|---|
| FBillNo / io_id / as_id | String | Document number | Used as idempotency key by both systems to avoid duplicate pushes |
| FStockId.FNumber ↔ wms_co_id | String | Warehouse code | A warehouse mapping table must be built; Jushuitan sub-warehouse codes correspond one-to-one with Kingdee's FNumber |
| FSupplierId.FNumber ↔ supplier_id | String | Supplier code | Often requires lookup on the extension field F_QKMS_JSTBM to maintain the mapping |
| shop_id ↔ FCustomerID | String | Shop code to customer code | Jushuitan shops are e-commerce shops, requiring corresponding customer profiles on the Kingdee side |
| FMaterialId.FNumber ↔ sku_id | String | Material/product code | The bridge of master data between the two systems; must be opened first |
| FQty / FGainQty / FLossQty | Decimal | Quantity | Inventory gain uses FGainQty, inventory loss uses FLossQty—easy to confuse |
| FTaxPrice / FPrice | Decimal | Unit price | Distinguish tax-included vs tax-exclusive; Jushuitan amount is usually tax-inclusive total |
| FLot / FLot_FNumber | String | Lot number | Carried by inbound/outbound and transfers; date format should be unified to yyyy-MM-dd |
| F_QKMS_* | String | Kingdee custom fields | E-commerce-specific fields (tracking number, payment time, etc.) usually hang in this namespace |
| io_date / pay_date / end_time | DateTime | Date timestamps | Kingdee side requires date format conversion; Strategy 18 uses end_time to update confirmation-of-receipt date |
How to Configure on Qeasy
Qeasy Data Integration Platform encapsulates the Jushuitan and Kingdee Cloud Cosmic integration as two standardized adapters: the Jushuitan adapter covers both Qimen (奇门) and non-Qimen interface families (jushuitan.saleout.list.query, jushuitan.refund.list.query, /open/orders/out/simple/query, etc.), while the Kingdee Cloud Cosmic adapter provides models for materials, suppliers, warehouses, sales outbound, etc. by FormId.
In Qeasy, the typical configuration path is:
- Register authentication information for both systems in "Data Sources" (Jushuitan AppKey/ShopId, Kingdee account set/third-party login credentials).
- Use Qeasy's Field Mapper to configure header and detail line field correspondences, supporting four mapping types: DIRECT, CONSTANT, COLLECTION (lookup mapping table), and TRANSFORM (concatenation/formatting).
- Qeasy's Schedule Orchestrator supports setting execution frequency by strategy type, with layered scheduling for master data and business documents; retries, failure queues, and alerts are built in.
- Code mapping tables (material, customer, warehouse, supplier) are maintained through Qeasy's mapping table feature; unmapped codes automatically trigger alerts.
Cross-Solution Practical Highlights
- Master data first: The four master data sets—material, customer, warehouse, supplier—must be completed before business document sync; the query strategies in Strategy 2–7 should run every 2 hours to maintain mapping tables.
- Document type constants and organization constants must be configurable: Specific values like FBillTypeID=XSCKD01_SYS, FSaleOrgId=101, FStockOrgId=100 in Strategy 17 differ across customer environments and must be made configurable parameters.
- Dual-track for Qimen and non-Qimen: In real scenarios, e-commerce channels often use both Qimen and non-Qimen interfaces, requiring routing at the strategy layer (by shop_id or order_type) to avoid missing orders.
- JD returns use a dedicated customer: Both Strategy 19 and Strategy 23 require FRetcustId to be fixed to the JD-channel dedicated customer code, which must be maintained in the mapping table; otherwise returns cannot be correctly booked.
- Confirmation-of-receipt date update depends on reverse query: Strategy 18 cannot push directly; it must first call Strategy 20 to query the Kingdee sales outbound document, link FThirdBillNo=o_id to obtain FID, then perform BatchSave.
- Time window must not exceed 7 days: Jushuitan officially recommends a single query window not exceeding 7 days to avoid missing orders and timeouts; incremental tasks must roll forward every day.
Pitfall Retrospective
-
Confusing FGainQty with FLossQty: Inventory gain uses FGainQty and inventory loss uses FLossQty—the field names are similar but point in opposite directions, and it's easy to copy the wrong one when configuring. The safe approach is to use FBillTypeID in Qeasy's mapper to second-judge the type before binding the quantity field.
-
Hard-coded Kingdee organization/document type constants: Specific values of constants like FBillTypeID and FSaleOrgId vary widely across customer environments; hard-coding them means changing source code when switching customers. The safe approach is to extract them into Qeasy's global variables or customer-level configuration tables.
-
Inconsistent tax-inclusive amount convention in Jushuitan: Jushuitan amount defaults to tax-inclusive total, while Kingdee's FTaxPrice is tax-inclusive unit price and FAmount is tax-inclusive amount; writing amount directly to FEntryTaxAmount is fine, but switching to tax-exclusive will leave a tax difference that surfaces during financial reconciliation.
-
Date format 7-day sliding window missing orders: The incremental task uses today as the end time minus 7 days; if the task hangs one day, a document gap appears after restart. The safe approach is to pin the end time to the last successful end timestamp rather than current time.
-
Unmapped codes causing whole-batch failure: Missing shop_id or sku_id in the mapping table will stall the entire document. Be sure to configure "unmapped code → write to failure queue + alert" in Qeasy's mapper instead of throwing an error that interrupts the whole batch.
When to Choose This
Applicable to retail enterprises that run both Jushuitan e-commerce business and Kingdee Cloud Cosmic finance/supply chain, requiring bidirectional data flow for products, purchases, inventory, sales, and after-sales. The boundary is: this solution only performs document-level sync, not workflow/approval automation; if a customer requires the two systems to share a single approval flow, a deeper business-fusion approach should be considered.