Purchase Return Order Integration Strategy: Syncing Returns from JKY to Kingdee Cloud
What This Strategy Solves
In a supply chain integration project at a retail/manufacturing enterprise, purchase returns are high-frequency yet error-prone. The source system handles outbound and fulfillment, while the target system holds financial and inventory books — both must reconcile. This strategy addresses one specific need: pushing purchase return outbound orders (inouttype=205) from the source ERP one-to-one into Kingdee Cloud's PUR_MRB purchase return material order, with auto submit-and-audit, so both sides close the books the same day.
Data Flow and Field Mapping
Flow: Source ERP (outbound order, inouttype=205) → Qeasy Data Integration Platform (middleware) → Kingdee Cloud (PUR_MRB).
Header Field Mapping:
| Source Field | Target Field | Mapping Type | Transform Rule |
|---|---|---|---|
| goodsdocNo | FBillNo | DIRECT | {{goodsdocNo}} |
| inOutDate | FDate | TRANSFORM | DATE_FORMAT(inOutDate,'%Y-%m-%d') |
| vendCustomerCode | FSupplierID | DIRECT | {{vendCustomerCode}} |
| companyCode | FStockOrgId / FSettleOrgId / FPayOrgId | DIRECT | {{companyCode}} |
| goodsDocDetailList | FPURMRBENTRY | COLLECTION | direct array reference |
Detail Line Field Mapping (bound by platform buildModel conventions):
| Source Field | Target Field | Business Meaning |
|---|---|---|
| goodsNo | FMaterialId | Material code |
| quantity | FQty | Actual return quantity |
| unitName | FUnitId | Unit of measure |
| batchNo | Batch field | Required when batch-managed |
| productionDate / expirationDate | Production date / Expiry | Batch traceability |
| transHasTaxPrice / transNoTaxPrice | FTaxPrice / FPrice | Tax-included / Tax-exclusive price |
| taxRate | FEntryTaxRate | Tax rate |
| recId | FSrcEntryId | Source entry ID for traceability |
The header warehouseCode must be propagated to every detail line as FStockId, denoting the return warehouse.
How to Configure on Qeasy
On the Qeasy Data Integration Platform, this strategy is split into two nodes: Source (QUERY) and Target (EXECUTE), with field mapping and execution parameters handled in the middleware.
- Source highlights: API
erp.storage.goodsdocout.v2, method POST, fixed filterinouttype=205, pageSize=100. The incremental window uses_function from_unixtime(({{LAST_SYNC_TIME}}-86400),'%Y-%m-%d %H:%i:%s')as start and{{CURRENT_TIME}}-86400as end, with a 1-day buffer to avoid edge-case data loss. - Target highlights: API
batchSave, method POST. Fixed execution parameters: FormId=PUR_MRB, Operation=batchSave, IsAutoSubmitAndAudit=true, IsVerifyBaseDataField=true, SubSystemId=21. - Centralized code mapping: Material, supplier, warehouse, organization, and unit codes all flow through Qeasy's centralized code mapping capability. The standard practice we use at customer sites is to first ensure base data is synced between the two systems, then enable the document sync strategy.
Implementation Steps
We typically break the rollout into three phases:
- Incremental start point: Run a one-time full pull to backfill historical returns and set the LAST_SYNC_TIME baseline. On Qeasy, this is usually a manual run of the Source node with the window extended before go-live.
- Full trigger: Execute a full backfill on the night of go-live to validate code mapping, batch fields, and tax/price fields all land correctly on the target.
- Scheduling cadence: Source crontab is set to
*/20 7-23/4 * * *(every 20 minutes within every 4-hour block during business hours); Target crontab is set to13-59/30 7-23 * * *(every 30 minutes during business hours), forming a staggered source-pull + target-execute rhythm.
The safe approach is to run an "incremental + full dual-track" mode for two weeks, confirm no duplicates or missing documents, then tighten the windows.
Pitfalls and Lessons Learned
- Common mistake: passing inOutDate directly to FDate. The source field is a datetime string, but Kingdee only accepts
YYYY-MM-DD. You must apply DATE_FORMAT, otherwise the whole document gets rejected by the target. - warehouseCode only on the header: Kingdee PUR_MRB requires the warehouse on every detail line. Don't forget to loop and assign FStockId on each FPURMRBENTRY row.
- Pushing documents before base data is synced: When material/supplier/warehouse codes don't exist on the Kingdee side, IsVerifyBaseDataField=true will hard-fail. Stabilize the base data sync strategy first.
- Missing batch/expiry fields: For batch-managed materials, the trio batchNo / productionDate / expirationDate must all be present; missing one causes validation failure.
- Auto-audit overlooked: This strategy sets IsAutoSubmitAndAudit=true, meaning save equals audit. Dirty upstream data will generate audited-but-wrong documents on Kingdee. During early go-live, we recommend temporarily flipping it to false and reviewing manually for a week before enabling.
When This Applies — And When It Doesn't
Applies: Enterprises where the source ERP is the operational outbound system and Kingdee Cloud is the financial/inventory book, and purchase returns need to land near-real-time with auto-audit. Does not apply: Scenarios where returns must be edited manually before posting (auto-audit will commit bad data immediately); scenarios where the target requires AP netting rather than return-material posting (use AP documents, not PUR_MRB); and environments where the material master has not been aligned across both systems.