Return Order Sync in Practice: From Jushuitan After-sales to Kingdee Cloud Refund Bill
What this strategy solves
After the e-commerce warehouse receives a rejection and return, the after-sales document needs to close the loop between the e-commerce ERP and the financial ERP: inventory write-off, accounts receivable offset, and invoicing basis all depend on this single document. Manual re-entry is slow and prone to picking the wrong document type. This strategy does only one thing — pull the upstream e-commerce ERP after-sales orders (rejection returns) out by an incremental time window, convert them into the standard refund bill of the downstream financial ERP, and write them back.
Data flow and field mapping
The data flow is one-way: upstream e-commerce ERP → Qeasy integration platform → downstream financial ERP. The middle layer is responsible for time-window pagination, code mapping, status filtering, and document type selection.
| Domain | Upstream after-sales field | Middle layer | Downstream refund field | Note |
|---|---|---|---|---|
| Primary key | as_id | dedupe cache | billno | Single number贯穿, downstream does not renumber |
| Time window | modified_begin / modified_end | {{LAST_SYNC_TIME}} → {{CURRENT_TIME}} | — | Core of incremental |
| Status | status = WaitConfirm | re-check before write | — | Rejection returns go through WaitConfirm only |
| Shop | shop_id | code mapping table | customer_number | Customer code maintained via mapping |
| Document type | type | conditional branch | billtype_number | Rejection returns fixed as red-font sales outbound |
| Organization | — | constant | org_number / bizorg_number | Multi-org scenarios must slice by shop |
| Currency | — | constant CNY | settlecurrency_number | Default RMB |
| Lines | after-sales order lines | line pass-through | item code, qty, warehouse | Header and lines staged separately |
How to configure on Qeasy
Step 1, build the source connector. Pick API /open/refund/single/query, method POST, write the pagination params page_index and page_size to 50, use the platform built-in variables {{LAST_SYNC_TIME|datetime}} and {{CURRENT_TIME|datetime}} for the time window, and filter status with status=WaitConfirm. Step 2, build the target connector. Pick API /kapi/v2/im/im_saloutbill/batchAddV2, method POST. Step 3, build the mapping strategy, align header fields one by one, and use Qeasy's "line pass-through" mode for line items to avoid manually拼接 JSON. Step 4, attach the schedule: source 05,35 8-22 * * *, target 20,50 * * * *, source before target, leaving processing time.
Code mapping is centrally placed in Qeasy's mapping table. Shop-to-customer code and document-type-to-organization code are all maintained in one table, so customers adding new stores do not need to modify the strategy.
Implementation steps
Run in three phases. Phase 1, full trigger, sync all historical WaitConfirm after-sales orders at once as a baseline. Phase 2, switch to incremental. The schedule rolls automatically according to the source time window. {{LAST_SYNC_TIME}} lands in persistent storage after each successful batch, so breakpoint rerun will not lose orders. Phase 3, daily operation. The source extracts every half hour, the target lands every hour twice, with enough buffer.
Three things to do before going live: check the shop codes and customer codes in the mapping table once; run a real rejection order through red-font outbound in the test environment; prepare an idempotency comparison table, using the upstream as_id as the unique key, so that write-back failures do not cause duplicate landings on retry.
Pitfall review
Pitfall 1: duplicate pull at the time window boundary. modified_begin as closed interval and modified_end as open interval looks stable, but server clocks drift, and orders modified within the same minute will be lost. The stable做法 is to add a 1-minute overlap window in the middle layer, and rely on as_id idempotent dedupe on write.
Pitfall 2: wrong document type. Rejection returns must go through red-font sales outbound, not ordinary sales outbound, otherwise the inventory write-off direction reverses. The pitfall is that during testing, using ordinary outbound looks correct, but at month-end closing you discover inventory is overstated.
Pitfall 3: shop-to-customer code hardcoded. Writing mappings in strategy scripts means you have to release a version every time a store is adjusted. The common customer应对模式 is to extract all mappings into the Qeasy mapping table, look up at runtime, and store changes only modify one table.
Pitfall 4: header and lines submitted at once. When there are many line items, submitting the whole batch is easy to timeout and truncate. Staging is more stable: first land the header to get the downstream document number, then use batchAdd per line to append details, and failed line retries do not affect other lines.
Pitfall 5: rejection and normal returns run together. The type field is not distinguished, rejection orders and normal return orders go through the same strategy, and the financial side sees all return reasons as "rejection". The stable做法 is to add a type conditional branch at the source, go into different mappings, and land on different downstream document types.
Applicable and non-applicable scenarios
It is suitable for scenarios where the e-commerce ERP and the financial ERP are integrated, where rejection return documents need to be synced by incremental time window, and where the downstream uses red-font sales outbound to write off inventory and accounts receivable. It is not suitable for complex groups where cross-legal-entity organizations need to split accounts receivable, nor for customer service return modification scenarios that require real-time second-level response — the latter should use a message queue plus manual review channel.