Sales Return Inbound Order Sync in Practice: Kingdee Cloud Cosmic → SWMS

What This Strategy Solves

Returns tend to get stuck at the moment the document reaches the WMS. Customer service approves a return in Kingdee Cloud Cosmic, but the warehouse has no idea the goods are coming until the end customer calls. The strategy we are going to walk through pulls sales return orders from Kingdee Cloud Cosmic incrementally by approval time, converts them into SWMS inbound orders (return inbound), and keeps the warehouse and finance aligned.

Data Flow and Field Mapping

The overall direction is: Kingdee Cloud Cosmic (source, QUERY) → Qeasy Data Integration Platform (middle layer) → SWMS (target, EXECUTE).

On the Kingdee side we call executeBillQuery for sales return documents. The key filter field is FApproveDate (approval date), the document number is FBillNo, the line unique identifier is FEntity_FENTRYID, and idCheck is enabled for idempotency. The request fields we care about:

Source field (Kingdee)	Meaning	Target field (SWMS)	Meaning
`FBillNo`	Bill number	`inOrderNo`	Customer order number
`FDate`	Business date	`estimatedArrivalDate`	Estimated arrival date
`FApproveDate`	Approval date	(used for filtering)	—
`FSaleOrgId.FNumber`	Sales org	`shipperCode`	Shipper code
`FRetcustId.FNumber`	Return customer	`customerCode`	Customer code
`FStockOrgId.FNumber`	Stock org	`houseCode`	Warehouse code
`FBillTypeID.FNumber`	Bill type	`orderType`	Order type
`FEntity_FENTRYID`	Line ID	`lineNo`	Line number
Line material code	Material	`sku`	SKU
Line quantity	Quantity	`qty`	Quantity

The table only lists the key fields; real configurations also include remarks, prices, batches and so on, taken on demand.

How to Configure on Qeasy

On the customer site we use the Qeasy Data Integration Platform. Configuration is split into four parts.

Source platform: select Kingdee Cloud Cosmic, API executeBillQuery, method POST. Primary key FBillNo, line primary key FEntity_FENTRYID, check idCheck=true, enable autoFillResponse so the platform expands the response structure automatically.
Target platform: select SWMS, API inbound order /inOrders/v4_1, method POST, primary key id, idempotency check on.
Field mapping: maintain the org/customer/warehouse mapping in a centralized code mapping table so it can be shared across strategies. Centralized code mapping is the most common pattern we see in Qeasy deployments; the material-create, customer-create, and return-inbound strategies all read from the same table.
Scheduling and filter: the source crontab is 0-59/5 * * * * (every 5 minutes from second 0), the target is offset by 3 seconds at 3-59/5 * * * * so the two ends do not collide. The filter condition is FApproveDate >= last successful timestamp.

Implementation Steps

We usually split one strategy into three phases:

Step 1: Incremental starting point. Run a cold start over a historical window (e.g. the last 7 days) to push all open return documents; this is a "full trigger", and we record the max approval time when it finishes.
Step 2: Full backfill. After cold start, trigger one more full run to backfill any documents that changed approval status in between; this overlaps with the first run, but idCheck deduplicates and there is no double inbound.
Step 3: Switch to scheduled frequency. Move the source crontab to a 5-minute incremental, keep the target offset, and turn on alerting so two consecutive empty runs or failures page someone.

We recommend going live in two waves—header first, then lines. First confirm the SWMS can receive the inbound order header; then release the lines to push materials, batches and quantities. This header-then-line staging compresses troubleshooting time from half a day to under an hour.

Pitfalls from Real Projects

Approval date is not business date. Many first-timers use FDate as the filter field, which silently drops cross-month backdated approvals. The safe choice is FApproveDate as the incremental key.
Hard-coded shipper code. Writing shipperCode directly into the request body means a multi-shipper customer will need code changes every time. The common pattern is to inject it from the mapping table as a variable.
Return customer vs. original sales customer. Kingdee return documents expose both FRetcustId (return customer) and FCustId (original sales customer). Push the former to SWMS, otherwise the warehouse will call the wrong person.
Wrong idempotency key causes duplicates. Using FBillNo as the header idempotency key is fine, but if line items are pushed in batches, line-level idempotency must include FEntity_FENTRYID as well.
Inconsistent units of measure on lines. The base unit and sales unit on a Kingdee line are not always the same, while SWMS inbound expects the base unit. Without unit conversion the numbers can match but the case counts will not.

When This Applies and When It Does Not

Applies: return documents that need to reach the warehouse right after approval, with same-day reconciliation expectations, especially for multi-shipper, multi-org retail and distribution companies. Does not apply: cross-border returns that must clear customs first, returns with many in-transit status changes, and returns that need to be reworked and reshipped—these should be split into multiple strategies.