Authoritative Tutorial: Kingdee Cloud Skybridge → Ali Yida Bank Account Sync Interface Field Manual

What This Interface Solves

Across multiple real-world projects, we kept hitting the same request: bank account master data living in Kingdee Cloud Skybridge (the ERP) needs to be referenced inside Ali Yida (the OA) for reimbursement, approval, and payment workflows—but the two systems have no native bridge. This integration synchronizes CN_BANKACNT (KY bank account) from Kingdee to Yida's form instance, so downstream flows can share one source of truth. It also covers incremental/full sync, code mapping, sensitive field masking, and enterprise-grade retry semantics.

Interface Capability Overview

• Authentication: Kingdee's executeBillQuery uses OAuth/AccessToken (obtained via the integrated login API), with X-Kd-Suite-Access-Token in the header. Yida's /yida_vpc/form/saveFormData.json uses AppKey + AppSecret HMAC signing, with x-yida-app-type and Authorization signature strings in the header.
• Request structure: Kingdee side uses FormId=CN_BANKACNT, FilterString=FApproveDate>='{{LAST_SYNC_TIME}}', and Limit/StartRow pagination loops. Yida side submits via appTypeId + formDataJson (JSON string), supporting upsert semantics.
• Response structure: Kingdee returns {Result:{Records:[…],TotalPage,CurrentPage}}. Yida returns {data,success}.
• Pagination & incremental mode: incremental via FApproveDate filter, full sync by removing the filter; checkpoint progression—only after a successful batch does the platform advance LAST_SYNC_TIME.
• Frequency recommendation: since master data changes little, run every 6 hours or hourly during business hours (0 */6 * * * or 5 7-23 * * *).

Typical Field Mappings

Configuring on Qeasy

On the Qeasy Data Integration Platform, this interface is typically implemented as follows:

1. Adapter selection: source side picks "Kingdee Cloud Skybridge – Business Document Query (executeBillQuery)"; target side picks "Ali Yida – Form Data Write (saveFormData)". Authentication, signing, and pagination are all pre-wired.
2. Data source configuration: import CN_BANKACNT under "Integration Metadata"; Qeasy automatically expands nested fields (e.g., FBANKID.Fname) without manual JSONPath.
3. Field mapper: drag-and-drop covers the table above. Nested fields can be dragged directly; the system auto-generates $.FBANKID.Fname expressions. For enums like FForbidStatus and FACCOUNTTYPE, configure value-conversion functions directly in the mapper.
4. Scheduling & checkpoint: enable "Incremental Checkpoint" in the schedule policy; Qeasy injects LAST_SYNC_TIME into Kingdee's FilterString automatically and ensures the timestamp only advances after a successful batch.
5. Exception & alerts: the platform retries 5xx/timeout by default with 3× exponential backoff; 4xx business errors are not retried but written to a failure table, matching the design. Configure "≥3 consecutive failures → DingTalk/WeCom alert" optionally.
6. Sensitive fields: Qeasy's mapper supports a blacklist mechanism; check FLICENSEKEY, FBankServiceLoginId, etc. as "Do Not Write" to prevent leakage at the source.

Cross-Scenario Best Practices

1. Business key first: regardless of whether target is Yida, DingTalk, or any OA, start by designating FNumber-class business codes as the unique key. Everything else—incremental, checkpoint, cross-system reconciliation—depends on it.
2. Prefer FApproveDate for incremental: Kingdee master data almost always uses FApproveDate over FModifyDate, because the latter drags in draft data and pollutes downstream forms.
3. Distinguish nested fields by organization: in multi-org enterprises, the composite key of FBANKID + FUseOrgId must be mapped together, otherwise identically-named accounts cross-contaminate between orgs.
4. Sensitive fields must be explicitly excluded: bank account records contain online-banking auth passwords and login descriptions—never default to full-field mapping. Either whitelist fields or use Qeasy's blacklist.
5. Confirm upsert semantics on target first: Yida's saveFormData supports "update by unique field," but only if the form design pre-configures a "unique identifier." Otherwise every sync becomes an insert and creates dirty data.
6. Schedule around business peaks: during Kingdee's month-start and month-end closing, master data barely changes; scheduling hourly between 7:00–23:00 every 6 hours is sufficient, and avoids the 0:00–5:00 maintenance window.

Pitfall Retrospective

• Pitfall 1: incorrect JSONPath for nested fields—someone wrote FBANKID.FName instead of FBANKID.Fname. Kingdee is case-sensitive; the field came back null. The safe approach is to fully use Qeasy's visual nested-field selector, never handwrite paths.
• Pitfall 2: incremental sync pulled unapproved data—an early solution used FModifyDate, so draft-state accounts flowed into Yida and were picked in approval flows. Switch to FApproveDate and add status validation into the Kingdee query condition.
• Pitfall 3: duplicates created on the target—the Yida form had no unique-index configured; every sync inserted a new row, accumulating thousands of garbage records in six months. Always configure "bank account number" as the unique index in Yida form design before syncing, and check "upsert by business key" in Qeasy.
• Pitfall 4: online-banking password leak—one solution used default full-field mapping, pushing FLICENSEKEY into Yida and nearly causing a compliance incident. Any field involving login passwords or keys must be checked as "Do Not Write" in Qeasy's mapper and pass through manual review.
• Pitfall 5: 429 rate-limit brought the schedule down—Yida's saveFormData enforces QPS limits; one project triggered 200 requests/minute and got throttled, taking all downstream data with it. The safe approach is to enable token-bucket throttling at the platform layer, capping QPS ≤ 10, and back off according to Retry-After.

When to Choose

This pattern suits scenarios where "Kingdee Cloud Skybridge master data (bank accounts, currencies, departments, etc.) must be referenced by Ali Yida, DingTalk Yida, or other OA forms"—small data volume (under tens of thousands), low change frequency, tolerable delay (≤6 hours). It does NOT suit: bidirectional real-time sync, transactional financial consistency, or scenarios requiring Yida data to be written back into Kingdee—the latter should use a dedicated reverse strategy.