Single-Strategy Tutorial: Pulling After-Sales Refund Orders from LingXing ERP into the Qeasy Integration Platform

What This Strategy Solves

In one cross-border retail account, after-sales refund records lived scattered inside the ERP, and finance had to export and clean them by hand before reconciliation. What we did here is pull refund orders from LingXing ERP into the Qeasy integration platform on a stable time-window basis, so they become the single source of truth for refund write-off, stock rollback, and downstream bookkeeping. The strategy itself is a QUERY_ONLY flow — it only fetches data, it does not write back.

Data Flow and Field Mapping

Data leaves LingXing ERP, goes through the request builder and response parser inside the Qeasy platform, and lands on a placeholder target (the target is configured as a no-op write). The full chain is: LingXing ERP → Qeasy request builder → Qeasy response parser → placeholder write.

Key request field mapping (Source → Middle layer → Target):

The idempotency key combines id and amazon_order_id, with idCheck enabled so re-runs do not produce duplicates.

How to Configure It on Qeasy

Pick strategy type QUERY_ONLY and point the target platform at datahub (the Qeasy platform itself). On the source side, fill in the LingXing after-sale list endpoint afterSaleList with method POST. Build the request body through Qeasy's field binding using the time window and pagination parameters. Use a pagination strategy that increments offset by length until the response is empty.

The target is configured as a WebAPI placeholder (named "写入空操作"), method POST, with empty request and response structures — it only receives the parsed payload and stores it, it does not write back to the source system.

Pay attention to a few switches in the source metadata: autoFillResponse=true lets response fields flow back into the mapping panel automatically; buildModel=false means no model is pre-generated and we map fields one by one; idCheck=true turns on idempotency.

Implementation Steps

We follow a three-phase approach: incremental starting point, full backfill trigger, and recurring schedule.

Step 1 — Incremental starting point. On go-live day, start with a small window (for example, the last 7 days) to avoid flooding downstream with the full history. Set start_date to the first day of the current week and end_date to the day before the run, with time_type set to "by update time".

Step 2 — Full backfill trigger. After the incremental flow has been stable for one week, trigger a manual historical backfill. Slice the window by month (for example 2024-01-01 → 2024-01-31), finishing one month before moving to the next, so individual response payloads never grow too large to time out.

Step 3 — Schedule frequency. Run the daily job during off-peak hours. The raw crontab in the source material uses a five-field placeholder 1 1 1 1 1; in production we adjusted it to "every day at 02:30 AM".

Pitfalls We Have Seen

1. Be explicit about what the time window means. Whether time_type=1 means "by update time" or "by refund completion time" has to be aligned with the business. In one engagement the customer picked "by refund completion time", and refunds that had been initiated but not yet completed never showed up — reconciliation broke.
2. Do not push pagination length too high. A length of 50 is safe; bumping it to 200 caused occasional timeouts. Idempotent re-runs save you, so always keep idCheck on.
3. Beware duplicate amazon_order_id. The same refund can produce multiple records across status changes, so the primary key must be the LingXing auto-increment id, not the platform order number — otherwise later updates overwrite earlier states.
4. Centralize code mapping. Inside Qeasy, keep shop, currency, and refund reason enumerations in a single mapping table so a source-side change propagates everywhere, instead of being scattered across strategies and easy to miss.
5. Mind strategy dependency order. This strategy (sequence=B) depends on an upstream flow that pulls the Amazon shop id dimension first; only then should refund orders be filtered by shop. Otherwise you run into null pointers when shop id has not yet been fetched.

When to Use It, When Not To

Use it when you need a stable landing zone for after-sales refund details to power reconciliation or refund write-off reports, with time-windowed incremental pulls and idempotency. Do not use it when you need to push refund documents back into the business system to perform write-offs (that needs a write-type strategy), or when you need near-real-time, second-level synchronization — this strategy runs on a daily schedule and is T+1.