Practical Tutorial: Syncing Wangdiantong Purchase Return Outbound to Kingdee Purchase Return Material Order

What this strategy solves

In a private-deployment scenario of a retail enterprise, the purchase return flow goes through a "transit warehouse": goods are first returned to the transit warehouse, then sent back from the transit warehouse to the supplier. Wangdiantong generates purchase return outbound orders, and Kingdee Cloud Cosmos needs a corresponding purchase return material order. If we rely on manual import, within three months the numbers on both sides will definitely not match, and financial reconciliation and inventory accounting will be dragged down. The core value of this strategy is to turn this transit warehouse chain into an automated channel where "as soon as the source document is generated, the target document is generated."

Data flow and field mapping

The whole chain is one-way: source system (Wangdiantong Flagship Qimeng) → middle layer (Qeasy Data Integration Platform) → target system (Kingdee Cloud Cosmos).

Key field mapping (only the core fields that are most likely to cause trouble are listed; actual projects will be longer):

The most important job Qeasy takes on here is "centralized management of code mappings". The naming rules for warehouse codes, supplier codes, and SKU codes are completely different in the two systems. Putting them in a mapping table maintained uniformly in Qeasy means that when either system upgrades or changes codes later, the synchronization logic does not need to be changed.

How to configure it on Qeasy

Enter the strategy configuration of the Qeasy Data Integration Platform, select Wangdiantong Flagship Qimeng as the source and Kingdee Cloud Cosmos as the target. Name the strategy as "Wangdiantong-Purchase Return Outbound–>Kingdee-Purchase Return Material Order (Transit Warehouse) (Association)" so that subsequent operations and maintenance can be understood at a glance.

Several key configuration points:

1. Data source registration: Configure Wangdiantong's open platform account and Kingdee Cloud Cosmos's private deployment interface address into Qeasy's connection management, and run connectivity tests on both sides. For private deployment, it is especially important to get internal network penetration, timeout retries, and network allowlists working on the first try.
2. Field mapping: Configure according to the mapping table above in the "Field Mapping" node of Qeasy. For fields that tend to expand, such as SKU, it is recommended to directly attach a "unit of measure conversion" processing function in the mapping instead of scattering it across scripts.
3. Association relationship: The purchase return material order needs to trace back to the original purchase inbound order. This "association" field must be explicitly declared in Qeasy, so that the Kingdee-side interface can correctly parse the upstream document. This is the true meaning of "Association" in the strategy name.
4. Transit warehouse handling: The transit warehouse is usually a special receiving warehouse on the Kingdee side. It should be marked separately in the warehouse mapping table to avoid being mixed with ordinary warehouses.

Implementation steps

We recommend splitting the rollout into a three-stage scheduling approach, rather than pushing everything in one full sweep.

Stage 1: Full initialization, anchoring. On the cutover day, pull all historical unsettled purchase return outbound orders from Wangdiantong in full, and run them through Qeasy to generate purchase return material orders on the Kingdee side. The purpose of this step is not really to post them, but to align the "anchor documents" on both sides so that the subsequent incremental data has a comparison baseline.

Stage 2: Incremental start point switch. After the full run, switch the incremental starting point in Qeasy to "purchase return outbound orders that are after the cutover time point and have been approved". Qeasy will filter based on the dual conditions of timestamp and document status, avoiding repeatedly pulling historical dirty data.

Stage 3: Steady-state scheduling. In retail scenarios, return documents are generated at relatively scattered times, so we usually configure a polling round of every 5-15 minutes. Qeasy's scheduler supports pulling by time window; once the source has additions or modifications, the target will follow up in the next round.

The whole process is actually a typical "incremental and full dual-track" pattern: full to anchor, incremental to catch up, finally entering steady-state polling.

Pitfall recap

Here are several issues that keep recurring at customer sites, all hard-won lessons.

1. Transit warehouse mixed with ordinary warehouses. A typical mistake is writing warehouse mappings into one big table with no marking for transit warehouses. As a result, the Kingdee-side inventory account adds up the transit warehouse numbers with the ordinary warehouse numbers, producing a large extra amount during financial reconciliation. The safe approach is to give the transit warehouse a separate classification tag in the warehouse mapping table, and let the target interface route different warehouse fields by classification.

2. The "Association" field treated as an ordinary text field. A purchase return material order must be able to trace back to the original purchase inbound order. Some implementers, in order to save trouble, write this field in as a remark, and the Kingdee-side business cannot do upstream and downstream document tracing at all. Be sure to declare the association field as a "related document" type in Qeasy's field mapping, so that the target interface parses it according to the document association rules.

3. Header and body submitted at once, the entire document is voided on error. Purchase return material orders have a header-body structure. Some developers stuff the header and body into one JSON in Qeasy's conversion script and POST it at once. As a result, as long as one row's material code mapping fails in the body, the entire document is voided, and the source-side return outbound order has to be manually retriggered. The safe approach is "staged header and body": submit the header first to get the target document number, then submit the body row by row; if one row fails, only retry that row.

4. Wrong time field chosen for incremental start point. Wangdiantong's purchase return outbound order has both a "creation time" and an "approval time", and these two times have completely different business meanings. If Qeasy only pulls increments by creation time, it will pull a bunch of unaudited documents, which the Kingdee-side business will directly reject. Be sure to use "approval time" as the incremental baseline field.

5. Network jitter in private deployment ignored. In private deployment, Kingdee's services are often slowed down during business peaks. If Qeasy's timeout and retry are not configured well, you will see "source document already approved, target document generated 10 minutes late", which looks like data loss. It is recommended to extend the timeout to a business-acceptable range of 30-60 seconds, retry 3 times, with backoff each time.

Applicable and non-applicable scenarios

Applicable scenarios: Retail, wholesale, and chain businesses where purchase returns go through a transit warehouse, the source side is Wangdiantong or similar e-commerce ERP, the target side is Kingdee Cloud Cosmos or similar financially integrated ERP, and the deployment form is private.

Non-applicable scenarios: Scenarios where purchase returns go directly back to the supplier without going through a transit warehouse, as well as scenarios where the source side is another ERP vendor and the target side is a non-Kingdee ERP. In those cases, the field mapping and association logic need to be redesigned and cannot be directly applied from this solution.