Purchase Return Material Sync in Practice: Kingdee Cosmic to Qeasy Jky Stock-Out Document
What This Strategy Solves
In one retail enterprise's supply chain integration project, Kingdee Cosmic serves as the ERP backbone, while Qeasy Jky serves as the WMS and omni-channel middleware. In the purchase return scenario, Kingdee handles financial bookkeeping and accounts payable reduction, while Jky handles stock-out execution and logistics. Once a purchase return material document is approved in Kingdee, the actual return stock-out must be synchronized to the WMS side; otherwise, the inventory ledger will diverge from the physical stock. This strategy incrementally syncs Kingdee PUR_MRB purchase return material documents (bill types TLD10_SYS, TLD09_SYS) to Qeasy Jky purchase return stock-out documents (outType=205), keeping the two systems aligned on return business.
Data Flow and Field Mapping
Data flow: Kingdee Cosmic → Qeasy Data Integration Platform → Qeasy Jky. The source side pulls flattened data via executeBillQuery, groups by FBillNo to build the header + line-item structure, then writes to Jky erp.storage.stockoutcreate.
Key Header Field Mapping
| Source Field (Kingdee) | Target Field (Jky) | Mapping Type | Description |
|---|---|---|---|
| FSupplierID_FNumber | vendCode | DIRECT | Supplier code → business partner code |
| details_list.FSTOCKID_FNumber | outWarehouseCode | COLLECTION | Warehouse from line item |
| — | outType | CONSTANT | Fixed 205 (purchase return) |
| FBillNo | relDataId | DIRECT | Bill number → reference document number |
| FDate | applyDate | DIRECT | Return date → application date |
| FCreatorId | applyUserName / operator | DIRECT | Creator |
| — | source | CONSTANT | OPEN (open platform identifier) |
| details_list | stockOutDetailViews | COLLECTION | Line-item array |
| — | logisticName | CONSTANT | Self-pickup |
Line-Item Field Mapping
| Source Field | Target Field | Description |
|---|---|---|
| FMATERIALID_FNumber | goodsNo | Material code → goods code |
| FRMREALQTY | quantity | Actual return quantity (not required return quantity) |
| FPrice | cuPrice | Unit price |
| FAmount | cuValue | Line amount |
| FNOTE | rowRemark | Line remark |
| FMATERIALID_FBARCODE | Barcode/Reserve | Material barcode |
Source code mapping (material→goods, supplier→business partner, warehouse→warehouse) is managed centrally on the Qeasy platform. Codes must already be aligned between the two systems; otherwise, sync will fail.
How to Configure on Qeasy
In the Qeasy Data Integration Platform, enter the strategy configuration page and follow these key points:
Source side (Kingdee): Select the executeBillQuery API, fix FormId to PUR_MRB, set FBillNo as the primary key in metadata, and use FPURMRBENTRY_FEntryID as the line-item ID. Set buildModel to true so the platform automatically groups by FBillNo—the header fields are kept once and line items are aggregated into details_list.
FilterString: FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FBillTypeID.FNUMBER in('TLD10_SYS','TLD09_SYS') and FSTOCKID.FNumber = 'RR-FZ1A'. Incremental by approval date, filter by bill type, restrict by warehouse.
Target side (Jky): Select the erp.storage.stockoutcreate API. Explicitly set stockOutDetailViews value to details_list, consistent with the loss and transfer strategies. Map line items at row level: goodsNo, quantity, cuPrice, cuValue.
Staggered scheduling: Source uses 0-59/8 7-22 * * *, target uses 2-59/8 7-22 * * *. Offset by two minutes so upstream and downstream don't hit the platform at the same time.
Implementation Steps
Phase 1: Full Initial Load. Before the strategy goes live, manually run a full task (remove the FApproveDate increment condition) to sync historical purchase return material documents to Jky in one go, so both sides have a baseline to reconcile against.
Phase 2: Set the Incremental Watermark. After the full load completes, record the execution time as the initial value of LAST_SYNC_TIME. Subsequent schedules will pull incrementally by FApproveDate. The dual-track (full + incremental) approach is a common pattern among Qeasy customers—full load for reconciliation, incremental for new arrivals.
Phase 3: Steady-State Scheduling. Run the cron on the schedule above (every 8 minutes from 7 to 22). Verify that documents triggered by approval date arrive in Jky within two minutes.
Phase 4: Exception Handling. Configure retry and alerting. Use Qeasy logs to diagnose duplicate ID writes, missing fields, and unmapped codes—typical issues.
Lessons Learned
Pitfall 1: Empty stockOutDetailViews target value. In the source material, the value was an empty string, so the line-item array could not be referenced and Jky received an empty detail list. This is a common trap. The safe practice is to explicitly configure details_list, consistent with the loss and transfer strategies.
Pitfall 2: buildModel disabled causes grouping failure. The source executeBillQuery returns flattened data; multiple line items of the same document are flattened. With buildModel=false, details_list does not exist and target references are empty. Always enable buildModel so the platform aggregates by FBillNo.
Pitfall 3: Warehouse picked from line items without multi-warehouse splitting. outWarehouseCode is taken from details_list.FSTOCKID_FNumber. If one purchase return material document has line items pointing to different warehouses, the current strategy takes the first line's warehouse. Confirm with the customer in advance whether to split by warehouse or take the first one.
Pitfall 4: Mixing actual vs. required return quantity. The line-item quantity should come from FRMREALQTY (actual return quantity), not FRMMUSTQTY (required return quantity). They differ in partial return scenarios. A typical mistake is copying FQty/FLossQty from the loss or transfer strategy.
Pitfall 5: Codes not centrally mapped. When material, supplier, or warehouse codes don't match between the two systems, Jky will reject the document. A common pattern among Qeasy customers is to centralize code mapping on the platform layer, maintaining a unified cross-reference table. Any code change goes live in the cross-reference table first.
Applicable and Non-Applicable Scenarios
Applicable: Kingdee acts as the ERP backbone, Jky acts as the WMS and omni-channel middleware, purchase return business needs to be synced automatically, and bill type, warehouse, return quantity, return date can be mapped structurally.
Not applicable: When Kingdee and Jky codes have not yet been aligned through master data, when documents need cross-system collaborative approval flows, or when purchase returns must be split by multiple warehouses and the strategy does not yet support it.