Purchase Return Document Sync in Practice: From WMS to Kingdee
What This Strategy Solves
In the return workflow of a retail company, the front-end warehouse system first receives the purchase return outbound order, and the ERP side needs to post the corresponding purchase return material order. If this step is handled manually, it is slow and prone to inconsistencies in quantity, batch, and warehouse codes. We use Qeasy Data Integration Platform to handle this strategy: the return outbound order is automatically pushed to the ERP's purchase return material order based on field mapping, so both sides stay aligned.
Data Flow and Field Mapping
The data flow is one-way push: source warehouse system → Qeasy middle layer → target ERP. The middle layer is responsible for code conversion, field trimming, and document status completion.
Key field comparison (desensitized example):
| Business Meaning | Source Field | Target Field | Handling |
|---|---|---|---|
| Document No. | src_bill_no | tgt_bill_no | Direct mapping, target adds prefix to avoid duplicates |
| Return Date | return_date | biz_date | Unified to UTC+8 |
| Vendor Code | supplier_code | vendor_code | Lookup via code-mapping table |
| Item Code | sku_code | material_code | Lookup via code-mapping table |
| Return Qty | qty | base_qty | Written after unit conversion |
| Warehouse Code | wh_code | stock_org | Lookup via code-mapping table |
| Document Status | status | doc_status | 0/1/2 maps to Draft/Audit/Done |
| Remark | remark | memo | Truncated to 200 chars |
Centralized code mapping is a common pattern among Qeasy customers: keep the three major code tables (vendor, item, warehouse) in one independent data table, and have sync tasks only query this table. New stores can be onboarded later without modifying the strategy itself.
How to Configure in Qeasy
The configuration entry is in Qeasy's "Integration Strategy" module. Key configuration points are as follows:
- Source connector: Select the open API of the front-end warehouse platform, fill in the application credentials (actual keys do not appear in the strategy but are maintained in the connector).
- Target connector: The ERP, using its standard interface. It is recommended to enable "Failure Retry".
- Data source configuration: The incremental start point selects the timestamp of the last successful run; for full triggering, clear the target intermediate table and rerun.
- Field mapping: In Qeasy's visual mapping interface, connect according to the table above, and attach a "lookup" action for fields requiring code conversion.
- Script node: Used for unit conversion and remark truncation. Qeasy supports lightweight scripts, so there is no need to stand up a full service.
- Target writing: The target interface sometimes has limits on document body lines. It is recommended to set document batching in Qeasy, a common practice is 50 lines per batch.
Implementation Steps
We usually split this kind of document sync into three phases and proceed steadily.
Phase 1: Full initialization. First push all historical return outbound orders in full, sliced by date. In Qeasy, "Full Trigger" is an independent trigger entry that the operations team can click manually, so as not to affect online scheduling.
Phase 2: Incremental start. Set the incremental start point to the timestamp when the full run completes, and schedule every 10 minutes thereafter. The crontab expression in Qeasy should be written as */10 * * * *, with a serial constraint that "the next run only fires after the previous one succeeds".
Phase 3: Stable operation and backtracking. After running for a week, compare the document counts on both sides to confirm nothing is missing, then switch the strategy to automatic. A common Qeasy customer practice is the "dual track of incremental and full": keep a weekly full rerun window as a fallback verification.
Splitting header and body into phases is also a common arrangement on customer sites: get the document header running first, then handle the body separately to reduce integration complexity.
Pitfalls and Lessons Learned
Pitfall 1: Code mapping is not centrally managed. In earlier projects, vendor codes were scattered across multiple strategies, and adding a new store later required changing 5 strategies. The stable approach is to build a unified code-mapping table that all strategies query.
Pitfall 2: Time zones are not aligned. The source time carries a timezone, the target does not, so the dates on both sides differ by one day, causing the return date to be misaligned with the receipt date. When configuring, be explicit about "what is the source timezone, what does the target expect".
Pitfall 3: Status fields are overwritten. Once a target document is audited and someone manually edits the remark, the incremental run will overwrite the remark. A typical mistake is that the status field is not part of the mapping, but the remark is also mindlessly written back. The stable approach is to only write back documents in the "unaudited" status.
Pitfall 4: Document body line count exceeds the limit. The target interface has limits on the number of lines per submission, and large batch returns will error out directly. The configuration should add batching, controlling each batch within a safe value.
Pitfall 5: Failure retry causes duplicate documents. After an interface timeout, Qeasy automatically retries; if the target has no idempotent field, duplicate documents will be generated. It is recommended that the target use document number + line number as the idempotent key, and Qeasy should explicitly mark the idempotent field.
Applicable and Non-Applicable Scenarios
Applicable: Return document sync between the e-commerce front-end warehouse and ERP, with moderate data volume (within thousands of orders per day), clear field mapping, and a need for stable incremental.
Not applicable: Scenarios requiring two-way collaboration (e.g., both sides can modify document status); very large real-time batch sync (over 100,000 orders per day); and integrations where the source field semantics are unclear in early-stage systems.