Kingdee Cloud Sky & DingTalk Integration Handbook: Field Mapping and Pitfalls Across 17 Strategies
What This Interface Solves
The Kingdee Cloud Sky + DingTalk integration covers the entire enterprise expense reimbursement chain: it converts DingTalk-side reserve funds, reimbursement forms, payment requests, and employee rosters into Kingdee's expense requests, reimbursement bills, and repayment documents, while feeding Kingdee's employee, department, and supplier master data back into DingTalk as a hub. The value is bridging the last mile between OA approvals and ERP financial accounting, eliminating the manual cross-system handoff for reimbursements, payments, and master data.
Interface Capability Overview
- Authentication: Kingdee uses ExecuteBillQuery/Save/BatchSave WebAPI calls requiring org codes and user tokens within the tenant; DingTalk uses approval-flow open APIs (topapi/processinstance/get) and the smart HR roster API (topapi/smartwork/hrm/employee/queryonjob), requiring the enterprise CorpId and the app's AppKey/AppSecret.
- Request/Response Structure: Kingdee master-data queries return JSON arrays (containing FID, FNumber, FName, etc.); document writes use a FormId + Model two-layer structure. DingTalk approval forms are indexed by process_instance_id, with component values carried in the form_component_values array.
- Pagination/Incremental Mode: Kingdee query APIs support PageIndex/PageSize pagination; incremental sync filters by the ModifiedTime field, with daily reimbursements and reserve funds typically using a 7-day creation-time window.
- Code Mapping: Employees, departments, and suppliers are uniformly resolved through a hub (lookups by FName + FUseOrgId_FName to retrieve FNumber). The platform's field mapper's _findCollection is the key tool.
Typical Field Mappings
| Target Field | Type | Meaning | Field-Tested Notes |
|---|---|---|---|
| FBillNo | string | Document number | Prefer extend.business_id, the DingTalk approval business ID, to ensure idempotency |
| FBillTypeID | const | Document type | Personal loan FYSQ001_SYS, reimbursement FYBXD001_SYS, public payment FYSQ003_SYS — must be hardcoded |
| FDate | date | Application date | Source varies: reserve funds use the loan date, reimbursements use create_time, payment requests use the expected payment date |
| FStaffID/FProposerID | collection | Applicant | Lookup by payee + enterprise entity against the employee hub; same name across orgs will break |
| FDeptID/FExpenseDeptID | collection | Applying department | extend.originator_dept_name must be split on - to take the last segment before hub lookup |
| FTOCONTACTUNIT/FCONTACTUNIT | collection | Contact unit | Employee scenario is BD_Empinfo, supplier scenario is BD_Supplier — don't mix |
| FBankCnaps/FBANKCNAPS | string | Bank CNAPS code | DingTalk's field name varies across forms; both 大额行号 and 联行号 must be tolerated |
| FEntity | collection | Reimbursement details | Map sub-table row by row for amount, expense description, FRemark |
| FEntity_Link | collection | Offset link | Reserved for reserve fund write-off; reverse-lookup Kingdee FID + entry ID by FBillNo |
| FCausa | string | Reason | Merged from FEntity row FRemarks by the AfterTargetGenerate script |
How to Configure on Qingyi Cloud (Qeasy)
Qingyi Cloud wraps the Kingdee and DingTalk connectors as visual adapters. In Qingyi Cloud, calls to this interface typically follow a three-stage pattern: source-system connector + target-system connector + field mapper. First, configure the tenant, app ID, and org codes in the Kingdee adapter; then configure the CorpId and approval-flow instance in the DingTalk adapter. The field mapper automatically reads metadata from both sides and registers the 7 master-data strategies as hubs. The remaining 10 business strategies reference the hubs via _findCollection at fields like FStaffID and FDeptID, without writing lookup SQL by hand. Qingyi Cloud's strategy scheduler also ships with exponential-backoff retry and rate-limit policy templates — integration engineers only need to pick them in the visual UI to take effect.
Cross-Scenario Field-Tested Points
- Hub-first execution: Employee, department, and supplier master data must be fully synced before business-document strategies start; otherwise _findCollection misses will fail the whole batch.
- Never omit the org dimension: Same names for employees, departments, or suppliers across different orgs are common in DingTalk; FName must be combined with FUseOrgId_FName to pinpoint the Kingdee code.
- Truncate the department field before lookup: extend.originator_dept_name is typically a "Company-BU-Department" long string; a direct lookup will fail. Split on
-in the AfterSourceInvoke script and take the last segment. - Archive the reserve-fund chain: FEntity_Link in write-off and store-utility reimbursements depends on Strategy 11 (Kingdee personal loan → platform) being in place first as a data store; without it, the offset cannot be back-filled.
- Auto-merge FCausa: The reimbursement reason doesn't come from a single field; the AfterTargetGenerate script concatenates each FEntity row's FRemark with line breaks. Make sure this hook is enabled on the platform.
- Dedicated channel for error push: Strategy 17's DingTalk robot channel needs its own access_token and strategy ID list — don't mix it into the business strategy alert group.
Pitfall Replay
- Lookup failure halts the batch: When the employee roster isn't synced first, FStaffID lookups in reimbursement strategies return nothing. This is a common pitfall; the safe approach is to add explicit dependencies to hub strategies and set them as blocking prerequisites in the scheduler.
- Empty detail rows: Personal loans have no detail sub-table on the DingTalk side, but FEntity cannot be empty on submit. The safe approach is to use the AfterSourceInvoke script to construct a single detail row from the loan amount.
- CNAPS field-name drift: On the same DingTalk form, this field is named 大额行号 in one component and 联行号 in another; a hardcoded source field will occasionally yield null. Use a "try multiple source fields + fallback to empty" strategy in the field mapper.
- DingTalk 429 rate-limiting: Reimbursement peak days often trigger this; the default 3 retries aren't enough. Bump the DingTalk target connector's retries to 5 with a fixed 60-second interval — this has been validated across multiple customer projects.
- Reserve-fund linkage dead loop: When the write-off strategy can't find the linked loan, submitting without removing FEntity_Link will fail repeatedly. The safe approach is to wrap the parsing in try/catch in AfterTargetGenerate: on failure, skip the link and log a marker.
When to Choose
This integration fits mid-to-large group enterprises that have landed DingTalk OA approvals and use Kingdee Cloud Sky as their ERP, and want to automatically post employee reimbursements, public payments, and reserve funds into accounting. The boundary: if reimbursements run on Feishu or WeCom, or the ERP is Yonyou/Oracle, the core fields and document types become invalid and the mapping must be rebuilt for the new system.