Gift Sales Outbound Order Integration in Practice: A P→T Single-Strategy Playbook from WMS to Kingdee Cloud

What This Strategy Solves

In one real project with a retail enterprise, the business team raised a very specific issue: gift-type sales outbound orders on ToB channels were long being "self-issued and self-cleared" on the WMS side — the documents were indeed released, but the financial books never moved. The root cause wasn't a lack of integration; it was that gift outbound orders don't follow the standard sales outbound path — flag bits, zero amounts, and document types all need separate handling. Once mixed into the same strategy as normal orders, either gifts are missed or the receiving side rejects them.

We used the Qeasy data integration platform to spin up a dedicated strategy: pull gift sales outbound orders from the WMS side into the ERP side, with the target document type routed to "Other Outbound", while inventory direction and pick organization use preset values. This way the gift path doesn't compete with the normal order channel, and finance can reconcile separately at month-end.

Data Flow and Field Mapping

The overall flow is WMS side (outbound order query API) → Qeasy middle layer (clean, map, fill fields) → ERP side (batch save API).

On the source side, the strategy reads from the WMS outbound order query interface (POST, paginated), advances incrementally by stockout_id, and uses order_no as the business key. The middle layer does only light processing: check the gift flag → pick the document type → fill in default organizations → map detail-line warehouse, item, and quantity into ERP material codes.

The following table shows the key field correspondences (only differences, common fields omitted):

How to Configure in Qeasy

This strategy is configured in three blocks in Qeasy, following the same approach we've used for several other sales-order sync strategies for clients — centralized code mapping, phased header/body processing.

1) Source connector Select the source WMS instance, choose the API wdt.wms.stockout.sales.querywithdetail, method POST, with paging pager and business params in the request body, and map response fields to the unified internal model. Use stockout_id as the incremental field and order_no as the idempotency key.

2) Middle-layer processing

• Filter conditions: Add the gift flag (e.g., is_gift=1 or document type identifier) at the source-side filter stage so that normal orders are not swept in.
• Code mapping: Material codes, warehouses, customers, etc., are maintained through Qeasy's mapping tables. The most common approach at customer sites is to host the mapping files in Qeasy's resource center — change once, apply everywhere.
• Default values: Document type, stock organization, pick organization, and stock direction are filled with constants in the middle layer, avoiding a roundtrip to the source each time.

3) Target write Select the target ERP instance, choose the batchSave API, and submit the prepared FormModel in one shot. One subtle detail: the ERP's batchSave submits the entire document, and any header field validation failure rolls the whole document back. That's why pre-validation in the middle layer saves much more trouble than relying on error codes from the target side.

Implementation Steps

We recommend advancing this strategy in three phases, following the common "incremental start + full trigger + schedule frequency" dual-track pattern seen across the Qeasy customer base.

Step 1: Full backfill (pre-launch) Historical gift outbound orders are typically not large in volume (many projects have only a few thousand to tens of thousands), so run a one-shot full backfill to catch the inventory up to the ERP. Set pager page size to the source API's recommended value — usually 100–200 is stable.

Step 2: Incremental start point Park the source cursor at the stockout_id from the moment the full backfill completes, and use it as the incremental start. Subsequent increments only pick up new or modified orders greater than that value.

Step 3: Schedule frequency The source strategy uses */15 * * * * (every 15 minutes), and the target write uses */20 * * * * (every 20 minutes). The 5-minute offset leaves the middle layer a window for retries and field-filling. If gift order volume is genuinely low, the source can safely be relaxed to once every 30 minutes.

Step 4: Post-launch observation For the first 72 hours, watch three things: whether document type is correctly identified as "Other Outbound", whether inventory direction and organization fields are written back correctly, and whether duplicate documents exist on the target side. The first two can be checked directly in Qeasy run logs by inspecting the request body; the third relies on deduplication by FBillNo on the target ERP.

Pitfall Review

Pitfall 1: Mixing gift outbounds with normal orders in one strategy This is the easiest mistake to make. Once mixed, either gifts get filtered out by the normal-order filter (missed push), or the target-side document-type validation rejects them (errors). The safe approach is to split strategies by document type — one for gifts, one for normal orders, each independently scheduled.

Pitfall 2: Line items flattened into the header Gift outbounds often complete in a single line, but the API response's detail lines are still an array. In some projects, engineers take a shortcut and just grab the first line, ending up with wrong quantity and unit price — and finance is off by one line. The correct approach is to expand the FEntity array line by line, with the line count strictly matching the source.

Pitfall 3: Duplicate document numbers on the target side The idempotency key is order_no, but sometimes the ERP flags the number as already existing because of format or prefix collisions. A common fix is to enable idCheck=true on the source side and add another layer in the middle that does "query target by FBillNo, skip if exists" — rather than blindly retrying.

Pitfall 4: Ignoring the stock direction field In some ERP versions for gift outbounds, if FStockDirect isn't passed, it defaults to "inbound", which directly inverts the book direction. The middle layer must explicitly write 0 (regular outbound) and not rely on defaults.

Pitfall 5: No matching organization under multi-org setups A source-side warehouse code A resolves under ERP stock organization 106 but not under 100. When the middle layer fills the default organization, it must write based on the currently active stock organization, not a hard-coded value. If the enterprise runs multiple stock organizations, we recommend maintaining a "warehouse → organization" mapping in Qeasy's mapping table.

When It Applies and When It Doesn't

Applies: ToB channel gifts, promotional gifts, sample outbounds, after-sales replacements — any "non-sales order but inventory-book required" scenario. Order volumes from a few dozen to several thousand per day all fit.

Doesn't apply: Gift amounts that are negative, cross-org transfers, gift applications that need approval workflows, and scenarios requiring consolidated invoicing with normal orders — these belong to dedicated transfer strategies or should be handled at the order layer rather than the outbound layer.