JD Channel Sales Return Sync: Jushuitan Refund Orders to Kingdee Cloud via Qeasy
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) | Type | Notes |
|---|---|---|---|
| - | FBillTypeID | CONSTANT | Fixed XSTHD01_SYS (standard return) |
| as_id | FBillNo | DIRECT | After-sales ID as document number |
| - | FSaleOrgId | CONSTANT | Sales org 101 |
| - | FStockOrgId | CONSTANT | Stock org 100 |
| - | FRetcustId | CONSTANT | Return customer CUST0009 (JD fixed) |
| - | FSettleCurrId | CONSTANT | Currency PRE001 |
| items.receive_date | FDate | DIRECT | Date taken from line receive_date |
| remark | FHeadNote | DIRECT | Remarks |
| o_id | F_QKMS_NBDDH1 | DIRECT | Internal order no. |
| created | F_QKMS_DATEFKRQ | DIRECT | Registration time |
Line (items → FEntity) mapping:
| Source | Target | Notes |
|---|---|---|
| sku_id | FMaterialId | Material code |
| qty | FRealQty | Actual return qty (positive) |
| price | FTaxPrice | Tax-included price |
| amount | FAmount | Return amount |
| i_id | F_QKMS_SPTM | Barcode |
| properties_value | F_QKMS_SPGG | Spec |
| asi_id | FEntryID | Line 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
- Incremental starting point: Before go-live, page through all historical orders once to verify the
good_statusfilter and that everyFRetcustIdlands onCUST0009. In Qeasy this is a one-off manual trigger. - Schedule frequency: crontab
0-59/50 7-22 * * *, every 50 minutes during business hours; skip low-traffic overnight windows to ease source API pressure. - 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.
- Ongoing operations: Monitor whether
LAST_SYNC_TIMEadvances monotonically and whether theidCheckinterception rate stays in a sensible band (high rate meansmodifiedis flapping); alert when thresholds are exceeded. - 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:FDatemust come fromitems.receive_date, not from a header-level date onas_id. The source array may contain multiplereceive_datevalues—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 intoFRetcustId, Kingdee rejects the entire batch for missing master data. - 7-day window ignored: Jushuitan enforces a ≤7-day interval between
start_timeandend_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. modifiedflapping causes duplicates: Status changes (such as CS notes) updatemodified. Whenmodifiedis 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 peras_idin a short window so the same order isn't posted repeatedly.- Line count truncation: Jushuitan's
page_size=50is 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 surepage_indexauto-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.