Practical Tutorial: Standalone Gift Sales Return-Slip Integration

What This Strategy Solves

The "standalone" gift sales return-slip scenario refers to gift-returns that happen at stores or e-commerce sites where the resulting return slip has no link to any positive-price sales order in the source system — it is just an isolated record. Finance and supply-chain teams still need to post it into the ERP as a real inbound and offset the cost. The common pain points are: the document type must be "Other Outbound" (其他出库单), the owner and inventory org are hard-coded, and the gift has no sales order to attach to. We hit this in a retail client engagement: during a promo peak, gift returns surged, warehouse manual re-entry got messy, and within three weeks the two ledgers no longer matched. Below is how this kind of strategy is delivered on the Qeasy data-integration platform.

Data Flow and Field Mapping

Overall direction: source system (return slip) → Qeasy middleware (clean, map, validate) → target system (Other Outbound).

Worth noting: the source API is wdt.wms.stockin.refund.querywithdetail (POST, paginated query) and the target API is batchSave (POST, batch save). Both are POST but semantically different — one pulls, the other submits.

How to Configure on Qeasy

On the Qeasy platform we organize this as "one source strategy + one target strategy + one data flow":

1. Source strategy: type QUERY, bound to wdt.wms.stockin.refund.querywithdetail, with idCheck=true and order_no as the idempotency key. pager and params are configured through the visual parameter panel; page size is tuned to the client's slip volume, usually 50–200.
2. Target strategy: type EXECUTE, bound to batchSave. Document number, orgs, owner, and doc type are hard-coded in the request body; dynamic values use {{order_no}} and {{modified}} style variable references.
3. Data-flow orchestration: the middleware layer handles three things — status filtering (only audited slips pass), warehouse→org mapping, and line assembly/dissection. The mapping table is maintained centrally on the platform, avoiding sprawl across strategies.
4. Header / body in phases: phase 1 pushes only the header with an empty body to validate the chain; phase 2 opens the line writes. This phased header-then-body pattern is a common approach we use with retail clients so any issue is easy to trace.
5. Scheduling: the source strategy runs on */15 * * * *, the target on */20 * * * * — the target lands a beat later, leaving a validation window.

Implementation Steps

• Phase 1: Incremental starting point. Use modified > project kickoff date as the initial window, run 1–2 cycles, confirm slip numbers match on both sides.
• Phase 2: Full-volume trigger. Open the time window and run a one-time historical backfill. When the target allows duplicate documents, idempotency check must be on.
• Phase 3: Steady-state scheduling. Source pulls every 15 minutes, target pushes every 20 minutes. Qeasy automatically accumulates unprocessed data and resumes after a break with no manual effort.
• Phase 4: Reconciliation loop. Run a daily document-number + amount reconciliation between the two ends; differences are pushed to a retry queue.

Lessons Learned

1. Typical mistake: wrong doc type. A gift return is essentially an "inbound reversal", but because the gift has no sales order, choosing Sales Return will be rejected by the target. The safe default is QTCKD01_SYS (Other Outbound).
2. Warehouse code ≠ org code. The source warehouse_no cannot be written directly into FStockOrgId; it must go through the mapping table or org isolation will break.
3. Idempotency lives only on the header. When order_no repeats, the target may report success but actually update incorrectly. Push idempotency down to the Qeasy platform layer instead of relying on the ERP.
4. Missing line fields. Gift lines may have no standard cost, which the target's validation will reject. The middleware should fill in a default cost or have the implementation consultant confirm zero-price is allowed.
5. Filter status early, not late. Filter out un-audited slips in the source strategy's post-response script — don't wait until they hit the target and bounce, which wastes quota.

When to Use and When Not

Use when: gift / promo returns without a sales-order link in retail, e-commerce, or chain-store environments; you need to book a cost-offset voucher in the ERP from an isolated return slip. Do not use when: the gift itself is linked to a positive-price sales order (use the ToB Sales Return strategy instead); you need batch or expiry-date accounting (the middleware must add batch fields, which this strategy does not cover); the return is an inter-org transfer (the org mapping logic differs).