Pushing Down to Kingdee Payment Bill After DingTalk Approval: A Single-Strategy Practical Tutorial

What This Strategy Solves

In a real-world project with a retail enterprise, the client raised a very typical pain point: payment application bills are first synced from Kingdee Cloud to DingTalk for approval. Once approved, the finance staff still has to manually go back into Kingdee to "push down" the payment bill — dozens of bills per day, each requiring several button clicks, and the workload explodes at month-end when payments are concentrated.

This strategy addresses the last mile of the approval closed-loop: once the DingTalk approval process completes, the integration layer automatically invokes the Kingdee Push interface to push down the approved payment application (CN_PAYAPPLY) and generate the payment bill (AP_PAYBILL). The integration side is only responsible for passing key parameters like the document number; field-level conversion is handled automatically by Kingdee's internal push-down rules. Combined with the Qeasy Data Integration Platform, the entire process requires no manual intervention, creating a complete closed-loop from "application → approval → payment" for finance operations.

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

The overall chain takes the form of Approval Event → Integration Layer → Kingdee Push-Down:

[DingTalk Approval Instance] --topapi/processinstance/get--> [Qeasy Middle Layer] --Push--> [Kingdee Payment Bill AP_PAYBILL]
        Document Number                                          Push Parameter Assembly          (Generated by Kingdee Internal Rules)

Key Field Mapping Table (this is the essence of the strategy — since there is no line-item mapping, the main table parameters are everything):

It is important to emphasize: This strategy has no line-item mapping. The line items of the payment bill are entirely auto-generated by Kingdee based on the payment application and the default conversion rules within the system — the integration side does not participate in field-level conversion. This is what makes it most different from a regular document sync strategy.

The sources of Document Number and status are empty in the DingTalk-side metadata, so the integration engineer needs to infer them based on the upstream strategy — typical sources are the extend.business_id field or a DingTalk form control that stores the Kingdee FBillNo.

How to Configure on Qeasy

When configuring this strategy on the Qeasy Data Integration Platform, we recommend organizing it into a four-stage flow: "Trigger → Data Retrieval → Mapping → Push-Down":

1. Trigger: Choose the "DingTalk Approval Completed" event trigger (or poll topapi/processinstance/get on a schedule to pull completed instances). If the upstream already has an event push mechanism, prioritize event-triggered mode to avoid latency from polling.
2. Data Retrieval Node: On the source side, select DingTalk's topapi/processinstance/get and pass the process instance ID to fetch the approval details. A small detail here: when the request/response metadata is empty, the platform needs to manually maintain an "inferred field table" for future maintenance reference.
3. Mapping Node: The mapping for this strategy is very thin — only 4 effective parameters (FormId, Numbers, Ids, TargetFormId, etc. are all constants or direct mappings). Qeasy supports centralized management of constants in the "Code Mapping Center"; constants like FormId, TargetFormId, RuleId, IsEnableDefaultRule, and IsDraftWhenSaveFail should be stored centrally to avoid scattering across multiple strategies where they become hard to modify later.
4. Push-Down Node: On the target side, select Kingdee's Push operation and POST the assembled parameters. Since IsDraftWhenSaveFail=true, when the push-down fails, a draft document will be generated on the Kingdee side for post-mortem troubleshooting.

Implementation Steps

We recommend rolling out in three phases to avoid troubleshooting difficulties from one-shot configuration:

Phase One: Incremental Starting Point (Gray Release Period) First get the single push-down chain working in the test environment. Manually initiate a payment application approval in DingTalk, and after approval, observe the integration logs to confirm that Numbers is passed correctly and whether the Kingdee side successfully pushes down and generates the payment bill. During the gray release period, recommend exposing only a small amount of real bills for manual reconciliation.

Phase Two: Full Trigger (Parallel Period) After the gray release stabilizes, switch the trigger from "manual trigger" to "approval-completed event trigger" so that all completed approvals automatically push down. During this phase, we strongly recommend enabling a dual-track of incremental and full sync: the incremental track uses real-time events to ensure timeliness, while the full sync runs once daily for reconciliation, filling in any bills missed by events. This is the most commonly used pattern among Qeasy customers, especially suitable for scenarios with high approval volume and zero tolerance for missed bills.

Phase Three: Stable Scheduling (Operations Period) We recommend setting the scheduling frequency to "event trigger + daily full sync fallback." The event trigger guarantees minute-level timeliness, while the full sync fallback ensures that bills are always posted within 24 hours. Also configure failure alerts — push-down failures usually mean Kingdee-side business validation did not pass (e.g., vendor not enabled, payment application not audited), requiring manual intervention.

Lessons Learned from the Trenches

This kind of "light mapping, heavy workflow" strategy may seem simple, but actually has many pitfalls. We've compiled several typical ones:

1. Misaligned source of Document Number is the number-one pitfall. If the DingTalk approval form does not explicitly store Kingdee's FBillNo, then Numbers will be empty during push-down, and Kingdee will directly report "document does not exist." The safe approach is to agree during the upstream strategy "Kingdee → DingTalk initiate approval" to use a fixed form control (e.g., extend.business_id) to store FBillNo, and document it in the specification.
2. "Silent drafts" from push-down failures can easily hide problems. While IsDraftWhenSaveFail=true is friendly, too many accumulated drafts mean finance never knows which bills failed to push down. Recommend adding a failure counter at the integration layer; when consecutive failures exceed a threshold, fire an alert — don't just rely on Kingdee returning 200.
3. Approval rejection also triggers push-down. When a DingTalk approval is rejected, pushing down without judgment will cause Kingdee to error. The safe approach is to add a "push down only when approved" filter in the trigger, or use a script to check status before mapping.
4. Repeated push-down of the same document generates duplicate payment bills. DingTalk approval-completed events may be triggered multiple times due to network retries. The integration side must be idempotent — in Qeasy, id is typically used as the idempotency key; check whether the document has already been pushed down before writing.
5. Kingdee push-down rules were changed by ops without notification. This strategy depends on Kingdee's internal "payment application → payment bill" default conversion rule. If finance or ops adjust the rule (e.g., changing the default receiving account), the integration side does not need to change code, but it must be communicated via the change notification process — otherwise the two sides' reconciliation will not match.

Applicable and Non-Applicable Scenarios

Applicable Scenarios: Financial closed-loop scenarios where the upstream is a Kingdee Cloud payment application bill that goes through DingTalk (or similar OA) approval, and after approval completion, a payment bill needs to be generated back in Kingdee; environments with moderate document volume, stable approval flow, and high idempotency requirements.

Non-Applicable Scenarios: Scenarios where the payment bill needs to add custom fields during the approval flow (this strategy cannot intervene in line-item mapping); complex processes where Kingdee actions also need to be triggered on approval rejection or transfer; environments where Kingdee has not enabled document conversion rules.