Sales Return Sync in Practice: A Single-Strategy Deep Dive from Kingdee Cloud Cosmos to Mabang ERP

What This Strategy Solves

A retail client had its return flow stuck between two systems: approved sales return documents in Kingdee Cloud Cosmos needed to push return-inbound information into the cross-border ERP Mabang for actual receiving. Originally each side re-typed the data, leading to scrambled records, mismatched inventory, and finance spending a week every month chasing discrepancies. Using the Qeasy Data Integration Platform, we turned this single "Sales Return: Kingdee → Mabang" flow into one strategy, achieving push-on-approval, rerunnable exceptions, and reasonable book-to-physical alignment.

Data Flow and Field Mapping

The overall flow is unidirectional: Kingdee Cloud Cosmos (source) → Qeasy middle layer → Mabang (target). The source side pulls approved return documents through executeBillQuery; the target side calls Mabang's warehouse-do-add-storage-in to write an other-inbound document.

Key field mapping (simplified):

As you can see, Mabang's interface lacks standard fields such as source document number and customer. Qeasy uses a pragmatic workaround—composing key information into remark—which is a common pattern in real projects: when target-side fields are insufficient, preserve traceability by stuffing information into the remark field first.

How to Configure in Qeasy

1. Source assembly: Choose Kingdee's executeBillQuery and tick FBillNo, FSaleOrgId, FStockOrgId, FApproveDate, FSalesManId, FCustId, FRetcustId, FSrcBillNo. Set number to FBillNo, id to FEntity_FENTRYID, and enable idCheck=true to prevent the same row from being inserted twice.
2. Middle-layer mapping: Code mapping is managed centrally. Mabang cannot directly accept Kingdee's organization code, so in the source-side warehouseName field we wrote _findCollection find name from ... where finance_code={{FStockId_FNumber}}, letting Qeasy resolve the warehouse name by finance code at runtime. This centralized code mapping approach is far more reliable than hard-coding inside each strategy.
3. Target assembly: Choose Mabang's warehouse-do-add-storage-in (POST), type=WebAPI, effect=EXECUTE. Set employeeName to the constant "金蝶单据同步"; use a template to assemble multiple source fields into remark; bind the data field directly to the source goods_list row array.
4. Response handling: No response write-back is configured, because this strategy only cares about "inbound succeeded". If you later need to push Mabang's inbound document number back to Kingdee, add a separate return-pass strategy.

Implementation Steps

We rolled out this strategy in three phases—increment start point, full-volume trigger, and scheduling frequency:

• Increment start point: On go-live day, take an explicit timestamp such as 2024-01-01 00:00:00 as the increment start point; afterwards only push return documents whose approval time is greater than this value. Qeasy records this start point, so reruns will not duplicate historical data.
• Full-volume trigger: On first launch, manually trigger one full-volume run to backfill any return documents accumulated before the increment start point. After the full run completes, switch to increment mode.
• Scheduling frequency: Source crontab 3-59/3 2-23 * * *—offset polling every 3 minutes between 2 AM and 11 PM; target crontab */5 2-23 * * *—execution every 5 minutes. The source runs denser than the target so data accumulates and is pushed to Mabang in batches, reducing interface pressure.

If three consecutive failures occur, Qeasy enters an alert queue for manual handling by on-duty staff. It does not retry infinitely in a loop—this is the safe approach.

Pitfall Review

1. A typical mistake is stuffing Kingdee's organization code directly into Mabang's warehouse field. Kingdee's FStockOrgId is an organization code, while Mabang wants a warehouse name—the types don't match. Using _findCollection for centralized mapping on the source side is much easier than writing scripts in every strategy.
2. Common pitfall: remark strings getting truncated by Mabang. Once we stuffed six fields into remark at once, and the resulting oversize string failed on insertion. The safe approach is to keep only document number, date, customer, and source document number—drop the rest to line-item remarks.
3. idCheck must not be disabled. If turned off, the same row gets inserted repeatedly, inflating Mabang inventory. We learned this the hard way during the first trial run and subsequently forced it on.
4. Midnight to 2 AM is Kingdee's daily settlement window. We excluded 0–1 AM from both crontabs to avoid querying documents during settlement when approved status may not be visible.
5. Modifying a strategy in Qeasy does not retroactively refill history. Once we adjusted the remark template and noticed historical documents' remarks weren't updated—then realized remark is a write-time snapshot and cannot patch source data afterwards. The safe approach: after a template change, run a separate retransmission for affected historical documents.

Applicable and Non-applicable Scenarios

Applicable: enterprises where Kingdee handles accounting and a cross-border ERP handles warehouse execution, with a need to auto-inbound approved sales return documents; stable document structure with warehouse codes already mapped. Not applicable: businesses that require quality inspection before inbound (add an interception strategy in between); projects where Mabang is the general ledger and Kingdee is only the front end (the direction should be reversed—sync the other way).