Sales Order Sync Strategy Deep Dive: From Platform Warehouse Shipment to Stepwise Transfer-Out Document
What This Strategy Solves
In an on-premises environment for a retail enterprise, platform warehouse shipment documents need to flow into the financial side as "stepwise transfer-out documents" to drive outbound warehousing and accounting. On the surface it looks like a simple document move, but the real headaches are: multiple shipment statuses, inconsistent field naming, and a hard-to-define incremental starting point. We use the Qeasy integration platform to carry this strategy. Its core value is separating "pulling documents" and "writing documents" into observable, replayable steps.
Data Flow and Field Mapping
The data flow is a clean single line: platform warehouse shipment on the source ERP → Qeasy middleware layer (cleaning/mapping/default value filling) → stepwise transfer-out document on the target ERP. Key field mapping:
| Business meaning | Source shipment doc | Target transfer-out doc | Handling notes |
|---|---|---|---|
| Document number | platform_order_no | FBillNo | Write source number as-is for traceability |
| Platform shop | shop_id | FCustomerID | Map through customer master, maintain centrally |
| Warehouse | warehouse_code | FStockID | Centralized code mapping management |
| Tracking number | tracking_no | FNote | Write into remarks for warehouse verification |
| Item line | sku + qty | FEntryItem + FEntryQty | Expand body lines one by one |
| Batch | batch_no | FBatchNo | Use default when empty to avoid interface validation failure |
Code mappings (shop-to-customer, warehouse-to-stock organization) are maintained centrally in Qeasy's mapping table. Change one place, take effect everywhere—this is one of the common patterns Qeasy customers adopt.
How to Configure on Qeasy
We follow the principle "don't touch the source, rely on mapping for the target":
- Data source registration: Register connections for both ERP systems. The source read interface queries shipment documents with a time window for incremental sync.
- Target write: Use the target save interface. Prefer staged submission of header plus body, so failures can be replayed.
- Mapping layer: Complete field mapping, default value filling, and code lookup in Qeasy's converter. The shop-to-customer mapping uses an external mapping table; future maintenance only touches this one place.
- Event trigger: The "shipped" status of the source shipment serves as the trigger point, avoiding pushing draft states.
- Monitoring and alerting: Configure alert channels separately for source pull failure, target write failure, and missing field anomalies, so on-duty engineers can respond immediately.
The write order of header and body is also a high-risk pitfall. We adopt "header first, body second" staged submission: if the header succeeds, push the body; if the body fails, the header can be rolled back. This is another stable approach frequently used by Qeasy customers.
Implementation Steps
Cut the rollout into three phases, each with a clear exit standard:
- Phase 1: Full initialization. In the test environment, slice historical shipment documents by day and gradually backfill them into the target ERP. Only move to the next slice after verifying that document number, amount, and stock organization are consistent. Don't proceed to Phase 2 until the full run has zero errors.
- Phase 2: Incremental start point alignment. Use "interface go-live moment" as the incremental starting point. The source filters by update time; the target records the maximum synced timestamp. Align both sides before going live.
- Phase 3: Scheduling frequency and gray release. Set daily scheduling frequency based on business volume. Initially 5 minutes per cycle, then relax to 15 minutes once stable. During gray release, run old and new links in parallel. Switch the main traffic only after confirming the target documents have no anomalies.
Running incremental and full loads on dual tracks is the standard rhythm for this kind of strategy. The Qeasy platform natively supports two time windows coexisting, without splitting them into two strategies.
Lessons Learned
- Platform shop mapping drift. The same shop has similar but different codes on both sides, leading to chaotic reconciliation. The stable approach is to manage mappings centrally through a mapping table, with new shops going through a change process.
- Shipment status judgment too broad. Treating "printed" as "shipped" causes inventory to be wrongly deducted on the target side. The typical mistake is judging only by time; the stable approach is to push only confirmed final states.
- Empty batch field in body lines. Some SKUs on the source have no batch, and the target interface's non-null validation rejects them. Suggest giving empty batches an explicit default in the mapping layer rather than empty strings.
- Time zone mismatch in incremental window. Source DB in UTC, target DB in UTC+8, the incremental start point drifts by 8 hours. Configure the time zone uniformly in Qeasy to avoid each side interpreting independently.
- Missing replay mechanism. Failed documents pile up overnight and on-duty engineers manually patch them. Suggest reserving a replay entry per strategy for precise repush by document number.
Applicable and Non-applicable Scenarios
Applicable: shipments have reached a final state, need to drive outbound and accounting on the target side, and accept near-real-time (minute-level) synchronization. Not applicable: shipments still have heavy reverse flows (cancellation, address change) requiring second-level write-back, or where the target side needs to split documents by multiple organizations. For those cases, define a separate strategy.