Practical Guide: Purchase Order to Sales Order Sync

What This Strategy Solves (Scenario & Value)

In a real manufacturing supply-chain integration, the upstream system issues purchase orders, while the downstream ERP is used for sales. When the buyer and seller belong to different organizations of the same legal entity, the purchase order must be converted into a sales order in the ERP so that downstream delivery, invoicing, and settlement can proceed. We use the Qeasy integration platform to handle this pipeline. The core value is centralizing organization, customer, and code mapping so that the numbers on both sides always agree.

Data Flow & Field Mapping

The flow is "source → Qeasy middleware → target." The source side uses queryTime as the incremental cursor, and the target side deduplicates by document number.

A common pattern among Qeasy customers is centralized encoding mapping: organizations, customers, employees, and document types are maintained in a single mapping table, so any upstream change only requires one update.

How to Configure on Qeasy

A typical configuration follows three stages: source interface → mapping → target interface.

Source side: Select the QUERY action of /order/orderList, method POST, bind queryTime to the global variable LAST_SYNC_TIME, and enable idCheck with poNo as the idempotency key. Note that the metadata explicitly states the API only supports queries within a 1-month span, so the incremental window must be carefully controlled.

Mapping layer: In the Qeasy visual mapping, map poNo to FBillNo, convert orgName to FSaleOrgId through a lookup table, and normalize FDate to yyyy-MM-dd via the prepareDate expression. Customer and salesperson mappings should sit in a "centralized encoding mapping" node rather than being hard-coded into individual strategies.

Target side: Select the EXECUTE action of the batchSave API, method POST, enable idCheck, and decide whether to turn on "save and audit" based on the customer's actual business. After the header fields are complete, map the purchase order line items to the sales order detail entity.

Implementation Steps

We recommend a three-phase rollout.

Phase 1: Build mappings, set the incremental starting point. Initialize four categories of encoding mappings in Qeasy: organization, customer, employee, and document type. Set the default LAST_SYNC_TIME to 00:00:00 of the integration date to avoid pulling all historical data at once.

Phase 2: Trigger full sync, backfill history. For purchase orders that were already in transit before the cutover, trigger a one-time full sync. A safe approach commonly used by Qeasy customers is the "incremental + full dual-track" pattern: the full task runs on a separate schedule and is disabled once complete, so it never competes with the incremental task for the same data.

Phase 3: Tune frequency, enable monitoring. Schedule the source at */2 * * * * and the target at */5 * * * *, staggering them to avoid concurrency. Configure failure retries (3 retries, 30-second intervals), exception alerts (IM or email), and a simple reconciliation dashboard showing "document number → sync status."

Lessons from the Field

1. queryTime span exceeding 1 month fails directly. A typical mistake is setting LAST_SYNC_TIME to more than a month ago, which causes the source API to refuse. The safe approach is to add a pre-check in Qeasy that automatically slices the query into multiple loops when the span exceeds 30 days.
2. Mixing purchase order numbers with target document numbers. Many engineers reuse poNo as FBillNo for simplicity. If the upstream allows document number modification, the target will end up with duplicates. The correct practice is to prefix the FBillNo with the source system identifier (e.g., PO-xxx) for traceability.
3. Missing customer master data causes the entire batch to fail. The batchSave API commits in batch mode—any single failure rolls back the entire payload. If the upstream introduces a new customer that has no record in the target, the whole batch is rejected. We recommend adding a "customer pre-validation" step in the mapping layer; missing records should be parked in a Qeasy pending queue first.
4. Roll out header and body in phases. Many customers try to push both header and body at once and end up with entire documents rejected due to partial line issues. The safer staged approach: get the header running first, confirm the document can be created, then attach the details.
5. Time zone and date format. If the timestamp returned by the source has no time zone, Qeasy treats it as UTC by default, resulting in an 8-hour offset when written to the target. Explicitly specifying the time zone in the mapping layer is the lowest-cost mitigation.

Suitable and Unsuitable Scenarios

Suitable: buyer and seller belong to the same legal entity, purchase orders need to be converted into internal sales orders to trigger delivery/invoicing, and both ends support batch writes. Unsuitable: cross-entity transactions (real sales orders should be used instead of self-conversion), scenarios requiring complex approval flow penetration (workflow integration is preferred over data sync), and cases where document fields differ drastically with no mappable pattern (master data should be remediated before any sync is attempted).