Return Document Two-Way Sync: Kingdee Other Outbound to Jushuitan Other Inbound in Practice
What this strategy solves
The return loop is the segment of the supply chain where inventory and book records most easily drift apart. A retail enterprise processes dozens to hundreds of returns per day. The source ERP records an "Other Outbound (Return)" document, while the e-commerce warehouse needs a corresponding "Other Inbound" document to reflect the physical return. If the two sides do not align, inventory will eventually drift—either the physical goods return but the system does not reflect it, or finance refunds per ERP but the warehouse never sees the goods. We use Qeasy Data Integration Platform to handle this reverse flow: Kingdee Cloud Galaxy Other Outbound (Return) → Jushuitan Other Inbound (Formal).
Data flow and field mapping
The pipeline is one-way push: Kingdee Cloud Galaxy → Qeasy middleware → Jushuitan. Qeasy handles three things: pull the source document, transform fields, and write back in the format agreed by the target system.
Key field mapping:
| Business meaning | Kingdee source field | Qeasy middleware | Jushuitan target field |
|---|---|---|---|
| Document number | FBillNo (Other Outbound) | Standardized number + prefix | io_refund_no |
| Document date | FDate | yyyy-MM-dd | in_date |
| Warehouse | FStockId | Warehouse code mapping | warehouse_code |
| Owner | FOwnerId | Owner code mapping | owner_code |
| Item code | FMaterialId.FNumber | Unified item code | sku_id |
| Quantity | FQty | Numeric validation | qty |
| Remarks | FNote | Pass-through | remark |
Two kinds of mappings must be centrally maintained in Qeasy: warehouse code mapping and owner code mapping. These two sets of codes are never identical between the two systems. A common practice among Qeasy customers is to turn the mapping table into a visual "code cross-reference," so that when a new warehouse is added or an owner changes on one side, only this table needs to be touched, not the flow itself.
How to configure in Qeasy
- Source connector: configure the Kingdee Cloud Galaxy data source. In a private deployment, confirm network reachability and interface account permissions. It is recommended to create a dedicated integration account with only query permission on Other Outbound documents—minimum authorization.
- Target connector: configure the Jushuitan interface channel, register the AppKey and signing secret (placeholders only after desensitization), and test connectivity in Qeasy.
- Strategy canvas: create a new "Kingdee → Jushuitan" sync strategy. Source document type: "Other Outbound (Return)"; target document type: "Other Inbound (Formal)".
- Field mapping: drag and drop fields according to the table above; warehouse/owner/item code should be linked to mapping tables.
- Write-back strategy: Jushuitan usually uses the "external document number" for idempotency. In Qeasy, prepend a prefix to FBillNo as the unique key, so that reruns do not generate duplicate inbound documents.
- Validation and logs: enable Qeasy's field-level logs (desensitized to retain only structure and length). When something goes wrong, check the logs first, then the original documents on both ends.
Implementation steps
We usually run in three phases to avoid overwhelming the counterpart interface with a full load from the start.
- Phase 1: Incremental starting point. First pull the past 24 hours of data using "document date = T-1" as a smoke test, confirming that fields align, the idempotency key takes effect, and no duplicate documents appear on the target side. This phase typically runs for 2-3 days of observation.
- Phase 2: Full load trigger. Historical return documents that need to be backfilled run as a one-time full-load task, sliced by document date in batches of 200-500 documents, to avoid triggering Jushuitan's interface rate limit. Once the full load is done, immediately switch back to incremental.
- Phase 3: Stable scheduling. Incremental tasks poll every 5-10 minutes (frequency depends on volume). In Qeasy, lock down the "fetch window"—for example, fetch [now-15min, now] each time—leaving tolerance for boundary documents.
Pay attention to the order of header and body processing: write the header first; only after the header succeeds, write the body line by line; if any line in the body fails, roll back the entire document. Never allow a "header in, body half in" dirty document.
Pitfalls revisited
- Typical mistake: pushing return quantities as-is, including negative signs. Sign conventions for return quantities in Kingdee can be inconsistent. In Qeasy, always add a numeric normalization step: force absolute value on all return quantities to avoid negative inventory on the target side.
- Typical mistake: idempotency key without prefix. Document number ranges between the two systems may collide. The safe approach is to have Qeasy generate unique keys with a business prefix (such as
KD-RET-), so even when the target system mixes documents from multiple sources, the origin is instantly clear. - Typical mistake: hardcoding warehouse mapping inside the strategy. When a customer adds a new warehouse, every strategy must be changed. The centralized mapping table must be placed in Qeasy's "common configuration," with strategies only referencing it, never hardcoding it.
- Typical mistake: retrying only the failed body line. When some lines fail to write, roll back the whole document and repush it entirely. Do not just patch the failed line, or you will get dirty data such as "some lines were manually edited, then overwritten by the repush."
- Typical mistake: ignoring the audited status on the source side. Draft-state Other Outbound documents should not be pushed; only audited-state documents enter the sync queue. Add a status filter in Qeasy to skip anything equal to "Draft" or "Temporary".
Applicable and inapplicable scenarios
Applicable: private deployment scenarios where ERP is the authoritative source for return finance and inventory, and the e-commerce WMS needs physical return inflow; stable return volume and standard document structure. Inapplicable: complex cross-entity or cross-owner multi-organization returns; scenarios requiring real-time second-level return flow (this strategy in Qeasy runs on minute-level polling, not real-time push); and processes where returns must be quality-inspected before being warehoused—this strategy defaults to "audit = putaway," so the inspection step requires a separate strategy.