Sales Order Sync in Practice: From a Front-End OMS to T+ Sales Delivery Notes
What This Strategy Solves
In retail and distribution, orders are created in a front-end OMS, but finance reconciliation, stock deduction, and invoicing all live in the ERP. When the business asks "post orders to finance the moment a sale is made," what we need to do is to land delivery notes from the front-end into the ERP's standard sales-delivery document. This article focuses on one of the most common strategies in that flow: sales order sync.
Data Flow and Field Mapping
The overall flow is: front-end sales system (the "source") → middle layer (an integration platform such as Qeasy) → ERP sales delivery note. The source exposes an order/delivery view; the target expects a standard delivery document; the middle layer does the translation.
Key field mapping (typical shape):
| Semantic | Source field | Middle layer | ERP field | Note |
|---|---|---|---|---|
| Document no. | order_no / bill_no | Pass through, add prefix | cCode | Prefix avoids collision with existing docs |
| Document date | order_time | Normalize to server timezone | dDate | Watch the 00:00 boundary |
| Customer code | customer_code | Lookup via customer map | cCusCode | Source and ERP codes usually differ |
| Warehouse code | warehouse_code | Lookup via warehouse map | cWhCode | Multi-warehouse must be explicit |
| Item code | sku_code | Lookup via item map | cInvCode | If item master is missing, the line dies |
| Quantity | qty | Pass through | iQuantity | ERP may only accept base-unit qty |
| Tax-inclusive price/amount | price / amount | Convert per target currency & tax | iUnitPrice / iMoney | Pricing policy is the biggest gap |
| Header custom fields | ext_fields_1..n | Central KV in middle layer | Custom 1..n | Keep header/body fields separated |
This table is the skeleton. In real projects we usually turn it into a maintainable mapping sheet on the integration platform rather than letting it live inside scripts.
How to Configure on Qeasy
On the integration platform, we usually organize a strategy like this:
- Source pull: use the built-in source connector to incrementally pull by document type, filtered by "modified time > last sync time."
- Target write: use the target connector to call the ERP's sales-delivery create API.
- Field mapping: map source-to-target fields one by one. Codes (customer, item, warehouse) go through lookup nodes, not hardcoded transforms — this is one of the most common patterns we see on customer sites: centralized code mapping.
- Validation node: before write, validate that qty > 0, tax rate is known, warehouse code is in the whitelist. Failures go to an exception table, not discarded.
- Idempotency: deduplicate on "source doc no. + ERP doc no." to avoid double-posts breaking reconciliation.
If the source produces large volumes and the ERP API is rate-limited, the middle layer must also chunk the payload — N records per batch with a few seconds between batches. Not visible on the UI, but critical.
Implementation Steps
We recommend a three-phase rollout:
Phase 1: Delta anchor. Pick a start time on the source (e.g. 00:00 of the go-live day) and treat everything after that with status "delivered" as the initial anchor. Verify the anchor before the first run — getting it wrong means either lost docs or duplicates.
Phase 2: Full backfill. Once the anchor is confirmed, trigger a one-shot full backfill of historical data. Full backfills are slow, and customers always ask "will it finish?" The safe approach is a dual-track delta/full: while full is running, delta must keep going (using a temporary anchor); once full completes, switch to the formal anchor so no doc is missed in the window.
Phase 3: Schedule frequency. Early after go-live, run every 5-15 minutes; once stable, move to whatever the business can tolerate (commonly 30 minutes or hourly). Retail volume is high — too low and docs pile up; too high and the ERP suffers.
Lessons Learned
Pitfall 1: Item master must exist before orders. Sales order sync depends on the item master. If the master is not built first, you get "orphan docs." Make item master sync a predecessor on the integration platform, or add an "item code exists?" pre-check.
Pitfall 2: Mixing header and body fields. Some teams dump header fields into body rows to save time; reporting later breaks. Keep header and body in separate stages: create doc with header only, then use an update node to fill the body. The ERP-side doc state stays much more controllable.
Pitfall 3: Timezone and date boundary. Source in UTC, ERP in Beijing time — cross-day docs land on the wrong day and break daily settlement. The middle layer must normalize timezone explicitly and add a guard window around midnight (e.g. hold cross-day docs until the next day).
Pitfall 4: Price and tax conversion. Tax-inclusive unit price, tax-exclusive unit price, tax rate, currency — semantics differ between systems. Do conversion only in the middle layer and keep raw source values for traceability.
Pitfall 5: Failed docs nobody watches. Everything looks fine in week one; two months later, thousands of failed docs pile up in the exception table. Hook the exception table to the enterprise's own alerting channel (email/DingTalk/WeCom) instead of leaving it unattended on the platform.
When to Use and When Not
Use when: order volume is moderate, a standard delivery document shape exists, and freshness requirements are in the 5-60 minute range — typical for retail and distribution. Do not use when: sub-second sync is required, stock must be strictly consistent at every second, or the two systems' APIs differ too much and heavy business rewrite is needed — those cases are better served by an intermediate database or custom development.