Qeasy Cloud
Get Started

JD Channel Sales Return Sync: Jushuitan Refund Orders to Kingdee Cloud via Qeasy

· 谢锴斌· Integration Solutions· 10 views· 4 min read
JushuitanKingdee Cloud销售退货Incremental Sync轻易云供应链集成

What This Strategy Solves

In an omnichannel retail business, JD.com refund orders must land as sales return stock documents in the financial system to close the inbound-and-refund loop. Doing this manually means the customer-service and finance teams reconcile hundreds of orders daily—error-prone and slow. This strategy pushes Jushuitan refund orders that have confirmed receipt (good_status='SELLER_RECEIVED') into Kingdee Cloud's SAL_RETURNSTOCK return document, completing the "buyer return → seller receives → Kingdee return inbound" pipeline. We use the Qeasy data integration platform to host this flow, centralizing source filtering, field mapping, and primary-key deduplication. Customer service only handles exceptions; finance only sees finished documents in Kingdee.

Data Flow and Field Mapping

The flow has three layers: Jushuitan QIMEN (source API jushuitan.refund.list.query) → Qeasy middleware (filtering, conversion, key construction) → Kingdee Cloud (target API batchSave, form SAL_RETURNSTOCK).

Header field mapping:

Source (Jushuitan)Target (Kingdee)TypeNotes
-FBillTypeIDCONSTANTFixed XSTHD01_SYS (standard return)
as_idFBillNoDIRECTAfter-sales ID as document number
-FSaleOrgIdCONSTANTSales org 101
-FStockOrgIdCONSTANTStock org 100
-FRetcustIdCONSTANTReturn customer CUST0009 (JD fixed)
-FSettleCurrIdCONSTANTCurrency PRE001
items.receive_dateFDateDIRECTDate taken from line receive_date
remarkFHeadNoteDIRECTRemarks
o_idF_QKMS_NBDDH1DIRECTInternal order no.
createdF_QKMS_DATEFKRQDIRECTRegistration time

Line (items → FEntity) mapping:

SourceTargetNotes
sku_idFMaterialIdMaterial code
qtyFRealQtyActual return qty (positive)
priceFTaxPriceTax-included price
amountFAmountReturn amount
i_idF_QKMS_SPTMBarcode
properties_valueF_QKMS_SPGGSpec
asi_idFEntryIDLine identifier

Lines are grouped by as_id; one Jushuitan return line maps to one Kingdee return line. qty is passed as positive to indicate inbound quantity.

Configuring in Qeasy

In Qeasy this strategy decomposes into a JstQM source resource, a Kingdee.Cloud target resource, one main strategy, and optionally a lightweight middleware script for dedup logic.

Source configuration: API jushuitan.refund.list.query, POST, page_size=50 maxed out, date_type=0 (modified time), good_status hard-coded to SELLER_RECEIVED, start_time uses {{LAST_SYNC_TIME|datetime}}, end_time uses {{CURRENT_TIME|datetime}}. The window must not exceed 7 days—this is a hard Jushuitan API limit.

Target configuration: API batchSave, form SAL_RETURNSTOCK, Operation=Save, IsAutoSubmitAndAudit=false (save only, finance approves offline), IsVerifyBaseDataField=true to let Kingdee validate master data, SubSystemId=21 sales module, BatchCount=5 to control concurrency.

Primary key design: concatenate {{as_id}}{{modified}} as both number and id, idCheck=true to enable dedup, buildModel=false to skip data modeling. When the same after-sales order is modified, the change triggers a re-sync instead of being blocked by dedup.

Implementation Steps

  1. Incremental starting point: Before go-live, page through all historical orders once to verify the good_status filter and that every FRetcustId lands on CUST0009. In Qeasy this is a one-off manual trigger.
  2. Schedule frequency: crontab 0-59/50 7-22 * * *, every 50 minutes during business hours; skip low-traffic overnight windows to ease source API pressure.
  3. First-run validation: Pick 3–5 cross-store, cross-date JD returns and manually verify header and line fields, document date, amount, and return customer in Kingdee before going live.
  4. Ongoing operations: Monitor whether LAST_SYNC_TIME advances monotonically and whether the idCheck interception rate stays in a sensible band (high rate means modified is flapping); alert when thresholds are exceeded.
  5. Compensation: Auto-retry on failure; persistent failures land in an exception queue where ops can click "rerun" in Qeasy without replaying the whole batch.

Lessons from the Field

  • Wrong date layer for FDate: FDate must come from items.receive_date, not from a header-level date on as_id. The source array may contain multiple receive_date values—configure array aggregation (first row or business rule), not a string. Classic pitfall.
  • Return customer not fixed: JD-channel returns must use CUST0009, not store-level mapping. If a store code slips into FRetcustId, Kingdee rejects the entire batch for missing master data.
  • 7-day window ignored: Jushuitan enforces a ≤7-day interval between start_time and end_time. The Qeasy schedule itself is fine, but if the service is paused for more than 7 days, the next run looks like "no data." Safe approach: after a long pause, run a manual backfill before resuming incremental.
  • modified flapping causes duplicates: Status changes (such as CS notes) update modified. When modified is part of the key, the platform treats the row as new and pushes again, triggering an update in Kingdee. Add a script in Qeasy to keep only the latest record per as_id in a short window so the same order isn't posted repeatedly.
  • Line count truncation: Jushuitan's page_size=50 is document-level, not line-level; one page may contain very few return orders. Don't assume 50 rows is enough during big promotions. Qeasy paginates automatically—just make sure page_index auto-increment is enabled.

When to Use, When Not To

Use for: e-commerce platform returns (especially channel-platform returns like JD) where the platform has confirmed receipt and finance needs a return inbound document. Don't use for: offline-store returns, unconfirmed-receipt returns (good_status ≠ SELLER_RECEIVED), workflows that need Kingdee-side auto-approval, or businesses that require per-store granular allocation of return revenue—this strategy funnels all JD returns into a single fixed customer.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-jushuitan-kingdee-cloud-8926-ok-dcb51afa

Comments