Syncing Worry-Free Card Sales Returns to Kingdee AR Receivables: A Single-Strategy Tutorial

What This Strategy Solves

In retail and distribution, "worry-free card sales returns" typically means customers return previously purchased worry-free card products. The system needs to translate this return action into a red-letter AR receivable on the finance side, so that sales returns and accounts receivable stay in sync. This is exactly the scenario we faced on-site: the upstream business system (hereafter referred to as the "source system") generates worry-free card sales return orders every day, and these orders must be incrementally synced by business date into Kingdee Cloud as AR receivables, with auto-submit and auto-audit. The pipeline looks like just "pull—write", but how you compose the bill number, align organization and customer codes, and loop detail rows — if any detail is missed, the two ledgers drift apart within three months. We handled this end-to-end with a single strategy on the Qeasy Data Integration Platform.

Data Flow and Field Mapping

The data flow is straightforward: Source system (worry-free card sales return order) → Qeasy middle layer (field mapping + transformation) → Kingdee Cloud AR receivable (AR_receivable).

Key Header Field Mapping

Detail row mapping: The target FEntityDetail directly references the source Items array as a whole; the platform writes rows in a loop. If the Items sub-field names later turn out not to fully match the Kingdee AR receivable detail fields, you must add value expressions at the detail level, or use scripts to perform row-level conversion. That is for later — first go live with the "whole reference" approach.

How to Configure on Qeasy

The whole strategy is built inside one Qeasy strategy, with source and target configured separately.

Source

• API: /api/QueryWFStockIn, type QUERY, POST.
• Primary key field: FBillNo, with idCheck and autoFillResponse enabled.
• Request parameters: PageNo=1, PageSize=500, FDateFrom={{LAST_SYNC_TIME|datetime}}, FDateTo={{CURRENT_TIME|datetime}} — pull by business date range from last sync time to current time.
• Response structure: header fields (FBillNo, FDATE, FSETTLEORGID, FCURRENCYID, FBillTypeID, FCUSTOMERID, FPAYORGID, FSALEORGID, FISTAX, FSALEDEPTID, FAR_Remark, etc.), and the detail array Items.

Target

• API: batchSave, type EXECUTE, POST.
• FormId: AR_receivable, Operation: BatchSave.
• Key flags: IsAutoSubmitAndAudit=true (auto-submit and audit), IsVerifyBaseDataField=false (skip base-data validation), ValidateRepeatJson=true (repeat validation on), InterationFlags=CRE_ExceptionInfo.
• Configure field mappings per the table above. Focus on the FBillNo concatenation function and the constant A for FCancelStatus.

Centralized code mapping: FSETTLEORGID / FPAYORGID / FSALEORGID / FCUSTOMERID (orgs and customer) are direct passthroughs, but only if both sides share the same master-data codes. On Qeasy we maintain a single org-customer code-mapping configuration. If mismatches show up later, fixing the mapping once repairs every dependent strategy — no need to touch each one.

Implementation Steps

Roll out in phases, so you don't hammer the target system with a full sync on day one.

1. Incremental starting point: Set the source crontab to 10 */4 * * * (10th minute of every 4th hour). On the very first run, set LAST_SYNC_TIME to a clear business start date (for example, the day before go-live) so that incremental pulls start from that point and historical data is not re-fetched.
2. Full sync trigger: On go-live day, during a business off-peak window, manually trigger a full sync to backfill historical worry-free card returns. Qeasy supports manually triggering a full QUERY + EXECUTE flow — confirm org, customer, and material master data are ready on the target side before triggering.
3. Schedule frequency: Set the target crontab to */5 * * * * (every 5 minutes). The source pulls every 4 hours; the target consumes every 5 minutes. This way, if the source accumulates a backlog, the target drains it quickly without noticeable lag.
4. Post-go-live observation: Watch at least 3 full schedule cycles. Verify that FBillNo is unique, AR receivables are not duplicated, and detail rows are complete. Only then ramp the schedule up to full production cadence.

Lessons Learned

• FBillNo composition is the linchpin: A classic mistake is to use the source FBillNo directly as the target bill number. On rerun or backfill, the target rejects the duplicate or, worse, collides with same-day data and produces dirty records. The safe pattern is "fixed prefix + business date YYYYMMDD + source bill number" — unique and traceable.
• Org and customer codes must align with master data: FSETTLEORGID, FPAYORGID, FSALEORGID, FCUSTOMERID are all DIRECT mappings, but only if both sides agree. Our very first on-site run failed because the source customer codes did not match Kingdee's, so AR receivable creation broke. The recommended approach is to maintain a centralized code-mapping table on Qeasy, populated by a master-data sync strategy that runs first.
• Don't "ship and see" for detail rows: Referencing FEntityDetail from Items is the fastest way to go live, but if Items sub-fields don't match the Kingdee AR detail field names, you'll hit a subtle "header succeeds, detail is empty" bug. The safe approach is to do a dry-run with a real API response before go-live, list the actual Items sub-fields, then add the missing detail mappings or scripts.
• Due date = business date is intentional: FENDDATE_H = FDATE means "due on the return day, no grace period". If the business later requires a 30-day account period, this expression must change — do not assume it.
• FCancelStatus is fixed at A: Every synced receivable is treated as normal, not cancelled. If you need to sync historical returns that were already reversed, route them through a separate cancellation flow — do not reuse this strategy.

When This Applies — and When It Doesn't

Applies: The source system produces worry-free card sales return orders incrementally by business date, and the target Kingdee Cloud already has org, customer, and material master data; return volume is moderate and fits a pull every 4 hours, write every 5 minutes cadence.

Does not apply: Return orders require complex approval workflows (this strategy auto-submits and audits, with no human step); the source Items fields differ significantly from the Kingdee AR detail fields and need heavy row-level conversion; or org/customer codes are chronically inconsistent on both sides and there is no master-data sync strategy to reconcile them.