Qeasy Cloud
Get Started

Sync Practice: Pushing Sales-Outbound Orders from a SaaS OMS to an On-Prem ERP

· 冯潇· Integration Solutions· 8 views· 4 min read
畅捷通T+Jushuitan销售订单同步轻易云供应链集成编码映射增量调度幂等设计

What This Strategy Solves

The e-commerce order hub emits a steady stream of sales-outbound orders every day, while the finance-side ERP expects properly structured sales invoices. The two sides speak different dialects—e-commerce talks in terms of "store + platform order number," while ERP talks in terms of "business partner + inventory code." What we need to do is push e-commerce sales-outbound orders into ERP sales invoices according to a defined rule set, and keep inventory, business-partner, and item-master data consistent across both sides. It looks like "moving a single document," but it is actually the foundation of the entire supply-chain integration.

Data Flow and Field Mapping

The overall chain is: Source sales-outbound order → middle mapping layer → Target sales invoice (header + lines).

Key field mapping (e-commerce side / middle layer / ERP side):

  • Document number: source platform order number / unified number / target invoice number
  • Customer identifier: source store code / code mapping table / target business partner code
  • Item identifier: source SKU code / code mapping table / target inventory code
  • Quantity: source outbound quantity / pass-through / target invoice quantity
  • Price and amount: source transaction price, discount allocation / converted to tax-included/excluded unit price / target unit price and amount
  • Warehouse: source shipping warehouse / warehouse mapping / target warehouse code
  • Date: source outbound time / normalized format / target document date

The two field categories most prone to failure are: first, code mappings from "store → business partner" and "item → inventory," which must be managed in a centralized mapping table rather than hard-coded in scripts; second, the price and amount dimension—e-commerce prices are mostly tax-included, while the ERP sales invoice must respect the customer's tax settings, so the conversion must happen explicitly in the middle layer.

How to Configure It in Qeasy

In the Qeasy data integration platform, we use a single strategy to carry the whole chain. There are four key points:

  1. The source interface is the e-commerce sales-outbound order query API, with an incremental cursor based on "update time + outbound status";
  2. The target interface is the ERP sales invoice creation API. Note that most ERPs do not support updates, so deduplication must be done at the source side in advance;
  3. In the middle layer, use the data-transformation component to centralize code mapping, amount conversion, date normalization, and header/line splitting logic—so that one change applies globally;
  4. Failure handling: document-level failures go to a retry queue; network-level failures auto-retry, to avoid half-success states.

Centralized code mapping is the most common pattern among Qeasy customers: turn the two mapping tables ("store → business partner" and "item → inventory") into maintainable resources, so when business changes, IT can update them without touching scripts.

Implementation Steps

We proceed in three stages, each with its own scheduling rhythm:

  • Stage 1: Align the incremental baseline. First, perform a full historical backfill, pushing historical outbound orders into ERP sales invoices according to the defined rules, to establish a comparison baseline for subsequent incremental runs.
  • Stage 2: Bring up the incremental schedule. Use the source document's last-modified time as the incremental cursor. A scheduling interval of 5–15 minutes is recommended, avoiding the source system's outbound peaks (e.g., on the hour or half-hour).
  • Stage 3: Full reconciliation sweep. Trigger a full comparison sweep during the daily business low (e.g., late night) to produce a discrepancy report for identifying missed or erroneous documents.

The dual-track approach—incremental plus full—is the key reason this strategy stays stable at customer sites: incremental ensures timeliness, full ensures consistency.

Pitfalls and Lessons Learned

  • Pitfall 1: Hard-coding code mappings inside transformation scripts. Whenever a new store or item goes live, IT has to ship a new release, which is highly inefficient. The safe approach is a centralized mapping table.
  • Pitfall 2: Price and amount dimensions misaligned. E-commerce prices are tax-included, ERP prices are tax-excluded, and the difference silently lands in "other expenses," breaking long-term reconciliation. The conversion must be made explicit in the middle layer.
  • Pitfall 3: Header and lines pushed in one shot. When the header goes through one API and lines through another, but they are not staged, lines may arrive before the header, and the ERP will throw "orphan line" errors. The safe approach is to stage header and lines—header first, then lines—or use a transactional composite API.
  • Pitfall 4: Wrong time field used for the incremental cursor. The source's "creation time" never changes, while "last-modified time" reflects status progression; using the wrong field causes missed or duplicate documents.
  • Pitfall 5: No idempotency. The source occasionally repushes the same outbound order, and the target ERP does not support updates, producing duplicate sales invoices. The safe approach is to deduplicate by document number at the source side, and add an idempotency key in the middle layer.

Suitable and Unsuitable Scenarios

Suitable: e-commerce and ERP belong to the same legal entity, with single-direction document flow, mappable codes, and convertible field semantics. Unsuitable: multiple legal entities sharing one ERP, tax-control semantics too complex to convert, or source document status that frequently rolls back—in the latter case, govern the source document lifecycle first, then integrate.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-p9210a3-jushuitan-9687-ok-da961cf3

Comments