Sales Return Order Audit Sync in Practice: Closing the Loop from DingTalk Approval to Kingdee Cloud

What This Strategy Solves (Scenario & Value)

In a real project with a retail enterprise, the sales return flow originally looked like this: stores submitted return approvals in DingTalk, and once the approver finished, someone had to manually click "Audit" inside Kingdee Cloud for it to take effect. One return order meant crossing two systems and two manual steps — error rates were high. We used the Qeasy data integration platform to own this link, with the goal of automatically pushing the approved result from DingTalk into Kingdee Cloud for audit execution, keeping document status consistent on both sides.

Data Flow & Field Mapping (Source → Middle Layer → Target)

The overall direction is: DingTalk (approval-completed events) → Qeasy middle layer (aggregation, filtering, field enrichment) → Kingdee Cloud (execute audit).

On the source side we query the DingTalk approval instance via the topapi/processinstance/get API. The key fields retrieved after approval are:

• Document number (单据编号): the unique identifier used for the downstream write-back; must strictly match the Kingdee-side code.
• Approver (办理人): the actual approver, used for audit traceability.
• Document date (单据日期): approval completion time; affects the business date on Kingdee.
• Return organization, business unit (退货组织、事业部): drive the organizational dimension on Kingdee; must be validated as non-empty in the middle layer.

On the target side we call the Kingdee Cloud audit API (Audit). The request body fields that need special attention are:

Tip: FormId is not the document number — it is the form model ID in Kingdee's document metadata. It is easy to fill in incorrectly; always confirm from the metadata list.

How to Configure on Qeasy

The configuration idea for this strategy inside Qeasy is "source + target + aggregation + trigger." Below are the configuration points we typically use on customer sites.

Source component (DingTalk): Choose the DingTalk connector. Pick the topapi/processinstance/get API, method POST, effect QUERY. Because we only care about approval-completed events, we usually filter by approval status in the middle layer rather than pulling back every instance.

Target component (Kingdee Cloud): Choose the Kingdee Cloud connector. Pick the Audit API, method POST, effect EXECUTE. Fill the request body using the table above, paying close attention to FormId — it must be SAL_RETURNSTOCK, and Numbers should reference the source "document number" via a variable.

Centralized encoding mapping: A common pattern at Qeasy customer sites is to keep organization and business unit mapping in a dedicated mapping table rather than hard-coding inside the strategy. That way, when new stores are added or organizational structure changes, only the mapping table is updated — the strategy stays untouched.

Header / body split into phases: This strategy only handles the header-level audit action; line-item details are synced by a separate strategy. Mixing header and body into a single request tends to produce dirty data such as "audited but lines not posted."

Dual-track full + incremental: In the early go-live phase we run a full sync of historical orders for reconciliation; once stable, we switch to incremental sync keyed off the approval completion time. Qeasy scheduling supports both running in parallel, so you can verify and then retire the full sync.

Implementation Steps

1. Confirm source fields: Inside the DingTalk approval template, confirm that the "document number" field matches the Kingdee-side code exactly — this is the foundation for downstream matching.
2. Build the middle layer: Configure the aggregation component in Qeasy to only pass through instances in the "approved" status; enrich the organization and business unit dimensions that Kingdee requires.
3. Configure the target call: Fix FormId to SAL_RETURNSTOCK in the request body and bind other fields via variables; start with IsVerifyProcInst set to true and observe failure logs for a period.
4. Scheduling frequency: For this project, the schedule is */3 * * * *, i.e., polling every 3 minutes. Because approvals are discrete events, polling too frequently increases API pressure, while polling too slowly makes users feel they have to "wait after approval." Three minutes is a reasonable compromise.
5. Incremental start point: Use the latest approval completion time as the incremental start point. If you need to replay history, switch to full sync — but be careful to avoid duplicate audits.
6. Observability and alerts: Configure retry and alerting. The most common causes of Kingdee-side audit failures are locked documents and missing upstream dimensions; track these two categories separately.

Lessons from the Trenches

1. FormId mistakenly filled with the document number: This is the most classic mistake. FormId is the form model ID in Kingdee metadata, not the business document number. We have seen customers submit the document number as FormId — the API returns success but nothing actually happens.
2. Missing InterationFlags: Without STK_InvCheckResult, return scenarios are frequently blocked by negative-inventory checks. In production we recommend always passing this flag and setting IgnoreInterationFlag to true to avoid interactive stalls.
3. Over-aggressive scheduling causes duplicate audits: In some projects, polling every 3 minutes without a proper incremental start point pulls in already-audited orders, generating dirty calls. The safe approach is incremental start point plus status field double-check.
4. Missing organization dimensions silently dropped: Some stores leave "return organization" blank in DingTalk, but Kingdee requires it — these tend to be silently skipped by default. We require non-empty validation in the middle layer; missing values should go straight to alerts rather than passing through.
5. Full and incremental running in parallel: This is the most common pitfall during early go-live — running full backfill and incremental at the same time causes the same order to be audited multiple times. You must run "full first, then incremental" and only switch after reconciliation is consistent.

When to Use and When Not to Use

Use when: Approval flow lives in DingTalk and execution flow lives in Kingdee Cloud for sales returns; store or organization counts are stable and encoding mappings can be maintained once.

Don't use when: Kingdee-side requires secondary manual confirmation (this strategy will skip manual steps); the business involves complex multi-level reversal or reject-and-resubmit flows — this strategy only covers the "approved → execute" segment.