Sales Outbound Red-Stub to Kingdee Cloud Sales Return: A Single-Strategy Sync Playbook

What This Strategy Solves

A retail enterprise generates a large volume of sales outbound documents every day. Among them are normal blue-stub outbounds and, just as importantly, red-stub outbounds caused by returns, rejections, and mis-shipments. If red-stub documents are naively treated as ordinary outbounds, the downstream ERP will mis-handle inventory direction, receivables, and tax logic. What this strategy does is identify red-stub outbounds upstream and rewrite them as sales return vouchers in the downstream ERP, so that books and reality stay aligned and traceable.

Data Flow and Field Mapping

The flow is one-way: upstream → middleware (Qeasy) → downstream ERP. Upstream is pulled incrementally via a WebAPI; Qeasy handles field cleansing, code mapping, and organization resolution; downstream is written through a batchSave call into the sales return voucher.

Key field mapping (sanitized):

Business Meaning	Upstream Field	Downstream Field	Conversion Note
Document No.	goodsdocNo	id	Required, idempotency key
Outbound Date	inOutDate	FDate	Pass-through
Red/Blue Flag	inouttype	(Branch)	Only red stubs, mapped to returns
Owner Type	ownerTypeId	FOwnerTypeIdHead	Dictionary mapping
Customer Code	channelCode	FRetcustId	Resolved via mapping table
Sales Org	FBelongOrgId	FSaleOrgId	Reverse-looked-up by customer + org
Stock Org	ownerName	FStockOrgId	Taken from upstream line owner
Doc Type	(Fixed)	FBillTypeID	Fixed as sales return doc type code

How to Configure in Qeasy

We use Qeasy to host this pipeline. Configuration is split into three parts:

Source endpoint: API erp.storage.goodsdocout.v2, POST method, incremental window bound to system variables LAST_SYNC_TIME and CURRENT_TIME, pagination via pageIndex / pageSize, document number as idempotency key, idCheck enabled.
Target endpoint: API batchSave, request body built per the downstream sales return voucher model. The three required fields (doc type, sales org, return customer) are sourced from the mapping table or upstream fields.
Transformation scripts: Cross-system code mappings (upstream code → downstream code) are maintained centrally in mapping tables — this is a common Qeasy customer pattern: centralized code mapping, avoiding redundant definitions in every strategy.

Implementation Steps

We recommend a three-phase rollout:

Incremental baseline: First run a manual trigger with the "red-stub + document status" filter to verify the end-to-end flow and confirm there is no red/blue confusion.
Full backfill: On go-live day, widen the time window to backfill historical red-stub documents, then immediately switch back to incremental mode.
Scheduling cadence: The source runs on a high-frequency schedule 1 6-23/2 * * * (every 2 hours from 6 AM to 11 PM); the target writes once a day at 20 3 * * *. This is the dual-track pattern of incremental plus batch: high-frequency pull for increments, low-frequency batch write to avoid downstream table locking at night.

Pitfalls From the Field

Red and blue mixed together: The upstream response typically contains both red and blue stubs; this is a classic trap. The robust approach is to filter for red stubs at the source side, not at the downstream.
Customer code not found: Downstream FRetcustId must be the downstream ERP's own customer code; passing the upstream code will always fail. In Qeasy we use _mongoQuery for centralized mapping, with the customer master sync strategy running ahead of this one.
Sales org many-to-one: One upstream customer may map to multiple downstream sales orgs; lookup by customer alone is not enough. We changed the rule to a joint reverse lookup by "customer code + stock org" to guarantee uniqueness.
Return date earlier than outbound date: Upstream sometimes writes inOutDate as the approval date instead of the original outbound date, breaking downstream period logic. We added a date sanity check in the transformation layer that raises an alert if the gap exceeds 30 days from the original voucher.
Idempotency key collision: If upstream re-pushes the same red-stub document, the downstream rejects it as a duplicate document number. Even with idCheck enabled, an explicit dedup at the transformation layer is still needed.

When to Use and When Not To

Use when: Upstream clearly distinguishes red and blue stubs, downstream ERP must carry negative business via a dedicated sales return voucher, and reconciliation is required at hourly granularity — typical retail, e-commerce, and wholesale scenarios.

Do not use when: Upstream does not distinguish red and blue stubs, or the downstream has no dedicated sales return voucher type (and red-stub outbounds are used as a workaround); also unsuitable for very high-volume, second-level-latency traffic, where a message bus beats scheduled polling.