Practical Guide to Return-Inbound Sync: End-to-End Delivery from Marketing Cloud to Kingdee Cloud
What This Strategy Solves
Return documents are often the most "forgotten" part of a supply chain. In one retail customer scenario, the marketing cloud produces a large volume of returns every day that need to flow back into the ERP on the finance side as red-letter inbound notes. If teams rely on manual export and import, the numbers on both sides drift within three months. The goal of this strategy is simple: pull returns whose status is "approved" from the marketing cloud on an 8-minute cadence and write them into the target system as sales-return inbound notes, with idempotency and traceability.
Data Flow and Field Mapping
The overall flow is: marketing cloud (query API) → Qeasy integration platform (middleware and mapping) → Kingdee Cloud (execute API).
The source side calls /erp/api/order/query/saleReturnOrder via POST. Key inputs include the dealer ID, order status, and a time window built from the variable {{LAST_SYNC_TIME|datetime}} to support incremental pulls. The target side calls /jdy/v2/scm/sal_in_bound via POST and writes back the document number after creation.
Key field mapping (representative items only, no fabricated numbers):
| Business meaning | Source field | Target field | Mapping note |
|---|---|---|---|
| Document number | number | id / remark suffix | Append to remark for traceability |
| Audit time | auditTime | bill_date | Use `{{auditTime |
| Customer name | organName | customer_id | Reverse-lookup ID via _findCollection |
| Shipping address | shippingAddress | contact_address | Pass through as-is |
| Source flag | Implicit | bill_source | Hard-code ISV |
| Remark | remark | remark | Append source and document number |
How to Configure on Qeasy
Configuration has three segments: source API, middleware mapping, and target API.
On the source side, hard-code status to 1 (approved) and drive the time window from a variable—this is the soul of incremental sync. Once you freeze a date, data keeps piling up. On the target side, fix bill_source to ISV so the document origin is explicit.
The middleware mapping is the heart of this strategy. The customer field carries a name rather than an ID, so we use Qeasy's _findCollection function to reverse-lookup the ID against an internal profile. The pattern we see most often at customer sites is to centralize this reverse-lookup in a single "encoding mapping table" so that adding a new customer is just appending one row—no interface change required.
For scheduling, the source runs */8 7-23 * * * (every 8 minutes during business hours) and the target runs */7 7-23 * * * (every 7 minutes). The 1-minute offset lets the source land data first and the target consume it after, avoiding out-of-order execution where the target outruns the source.
Implementation Steps
Phase one: align the incremental baseline. First perform a one-time full backfill to clear historical returns, then pick a clear timestamp as the incremental start. From there, every subsequent run advances LAST_SYNC_TIME. We have seen projects use the deployment day as the baseline, which means the first week is spent backfilling history.
Phase two: full-mode trigger switch. Qeasy supports a "full re-run" button, but full mode should only be enabled in a new environment or after major parameter changes. In production, daily operation stays on incremental—a dual-track model: full mode as a safety net, incremental as the daily workhorse.
Phase three: converge the schedule frequency. Run at a higher frequency (say every 5 minutes) for one or two days to observe API stability and data volume, then converge to 7–8 minutes. Higher is not always better—higher frequency puts more pressure on the source system and risks rate-limiting.
Phase four: roll out header and body in stages. A return document usually has a header and several body rows. Recommend stabilizing the header first, then enabling body writes. Otherwise, an entire-document failure couples header and body issues together, and troubleshooting becomes painful.
Pitfalls We Have Hit
First, customer ID reverse-lookup misses values. The source carries a Chinese name, while both sides may have space, full-width vs. half-width, or abbreviation differences. A reliable approach is to add a cleaning step in the mapping layer: trim whitespace and normalize full-width symbols before reverse-lookup.
Second, malformed time-window values. The source time field accepts either date or datetime. If the variable produces something like 0000-00-00 00:00:00, the API fails immediately. Recommend an empty-value guard in the middleware: when empty, fall back to "now minus 30 days."
Third, missing idempotency. Without a deduplication condition on rerun, the target generates multiple red-letter inbound notes. Qeasy uses the source document number as the idempotency key, so retries or source-side replays do not create duplicates.
Fourth, audit status not filtered. If status=1 is omitted, draft documents are also pulled and landed into the ERP, requiring manual cleanup.
Fifth, timezone drift. The marketing cloud returns Beijing time by default; if the target parses it as UTC, the date shifts by one day. This is most common in cross-region deployments—make sure both sides declare the timezone explicitly.
When It Fits and When It Does Not
Fits: cross-system return document sync where the source supports an incremental time window and the target supports idempotent writes, with high-frequency pulls during business hours. Does not fit: sources without a time field that force full scans, targets without idempotency keys, or historical data migration scenarios that span year/month boundaries and require reconciliation.