Stock Order Sync Strategy in Practice: Field Mapping and Scheduling from Cross-border ERP to Kingdee Cloud

What This Strategy Solves

In a typical retail enterprise's stock preparation workflow, cross-border shipments are generated on the cross-border ERP side, while the group's internal inventory and accounting live in Kingdee Cloud. When the two systems are not connected, shipment data has to be entered manually, leading to errors, delayed write-backs, and mismatches between books and reality. We used the Qeasy data integration platform to carry this strategy: periodically pulling shipped stock preparation orders from the cross-border ERP and landing them as transfer orders in Kingdee Cloud, so that shipments and inventory form a closed online loop.

Data Flow and Field Mapping

The overall flow is: Cross-border ERP (WebAPI query) → Qeasy middle layer → Kingdee Cloud (batchSave execution). The middle layer handles variable substitution, field alignment, and idempotency control; the source side never directly hits the target system.

The table below summarizes the key field mappings we delivered on-site. Read it through before writing any mappings:

After the header is set, the SKU lines from the cross-border ERP detail are written back to the Kingdee transfer order entries, where light field normalization is usually applied (such as unit, batch number, expiry date). Encoding mappings are centrally managed in Qeasy's dictionary tables, so future adjustments only require editing one place rather than hard-coded values across both systems.

How to Configure on Qeasy

Keep configuration restrained; do not pile up scripts right away. We suggest three steps:

1. Register connectors on both sides. In Qeasy, create access credentials for the cross-border ERP and Kingdee Cloud separately. The source side uses the QUERY type interface hwc-shippbatch-get-shipment-list, and the target side uses the EXECUTE type batchSave. Both use POST.
2. Configure request parameters. On the source side, bind timeLastModifiedStart to the Qeasy variable {{LAST_SYNC_TIME|datetime}}, and bind timeLastModifiedEnd to {{CURRENT_TIME|datetime}}. Keep the time window within 7 days—this is a hard constraint on the cross-border ERP side, not a Qeasy limit. Set pageSize to 20 and let Qeasy handle pagination automatically.
3. Write field mappings and transformers. Headers go through standard mapping, while business fields (such as owner, organization) go through dictionary mapping. The target FBillNo uses the concatenation rule {{shipmentId}}-FH to ensure idempotency and avoid duplicate pushes.

A common pattern we see with customers is: centrally managed encoding mappings, headers and lines handled in phases, incremental and full-volume running in parallel—first stabilize the headers, then scale up the line items.

Implementation Steps

Phased scheduling is the soul of this strategy. We recommend going live in the following order:

• Phase 1: Align the incremental starting point. Before the first run, manually adjust LAST_SYNC_TIME in Qeasy to a historically acceptable business time point (such as the day before project launch). The first round only pulls incremental data after that point, to avoid pulling everything at once.
• Phase 2: Full-volume trigger (optional). If there is historical backlog, you can supplement a full-volume run, using a temporary crontab to trigger all batches with status "shipped". Switch back to incremental mode immediately after the full run completes.
• Phase 3: Scheduling frequency. The source crontab is set to */10 2-23 * * *, i.e., every 10 minutes between 2:00 and 23:00 daily. The target crontab is set to 10-59/5 2-23 * * *, i.e., every 5 minutes from minute 10 to 59 of each hour. The 10-minute offset is intentional, leaving a buffer between fetching and landing.
• Phase 4: Exception handling. When Kingdee fails, Qeasy retries according to its retry policy. Batches that still fail after retries enter a manual repair queue, rather than piling up indefinitely in the pipeline.

Pitfall Review

Here are the high-frequency pitfalls we summarized from several customer engagements:

• Time window exceeding 7 days. The cross-border ERP interface explicitly limits the single-query time span to 7 days. If LAST_SYNC_TIME is not properly maintained, or the system clock drifts, you will see "interface errors" or "missing data". A safe approach is to add a pre-check in Qeasy that constrains the window to within 6 days 23 hours.
• Hard-coded status filter. Hardcoding status as 2 (shipped) may seem convenient, but if states like "signed for" also carry business meaning, data will be missed. We recommend making status a configurable parameter, so future business expansion only requires changing configuration, not the flow.
• FBillNo without an idempotency suffix. Using shipmentId directly as the Kingdee document number, when network retries or manual repairs occur, easily produces duplicate documents. A lightweight suffix like -FH costs almost nothing but blocks a large portion of duplicates.
• Hard-coded inventory org and owner type. During go-live, organization codes from the test environment were hard-coded; after migration to production, they were forgotten, causing documents to land under the wrong organization. Such fields are strongly recommended to use dictionary mapping rather than hard-coding into the flow.
• Source and target starting simultaneously. While the source is still pulling, the target starts landing, resulting in "half-baked documents". The 10-minute offset between source and target is specifically designed to avoid such race conditions.

Suitable and Unsuitable Scenarios

Suitable: Scenarios where cross-border shipments need to flow back to the ERP as transfer/in-out warehouse documents; supply chain integration with daily order volumes in the low thousands and real-time requirements at the 10-minute level. Not suitable: Scenarios requiring minute-level real-time inventory deduction (should use a dedicated real-time inventory strategy); scenarios with extremely large volumes and complex business validation (recommend first implementing lightweight shipment backflow, then considering a dedicated sales order sync strategy).