Authoritative Field Guide: Querying Kingdee Cloud Settlement Type

What This Interface Solves

In Kingdee–DingTalk integration scenarios, settlement types are essential master data for payment documents, expense reimbursements, and approval flows. This interface (ExecuteBillQuery / FormId: BD_SETTLETYPE) incrementally pulls settlement type master data from Kingdee Cloud based on modification time and delivers it to downstream systems for business selection, addressing pain points such as inconsistent payment codes across systems and untimely sync of new/disabled settlement types.

Interface Capability Overview

• Authentication: Kingdee Cloud OAuth / third-party token (managed uniformly in the Qeasy connector).
• Request method: POST, following Kingdee's generic query API style.
• Request body: contains FormId=BD_SETTLETYPE, FilterString, FieldKeys, Limit, StartRow, TopRowCount.
• Response structure: returns Result.ResponseStatus.IsSuccess and Result.Result array; each row contains Number, Name, SETTLECATEGORY, TYPE, PAYTYPE, etc.
• Pagination: uses Limit + StartRow loop; TopRowCount indicates total.
• Incremental mode: FilterString uses FModifyDate>='{{LAST_SYNC_TIME|datetime}}'; scheduled task 1 8-22 * * * runs every hour.

Typical Field Mapping

How to Configure in Qeasy

• Adapter: select the "Kingdee Cloud · ExecuteBillQuery" adapter from the Qeasy connector market; set FormId directly to BD_SETTLETYPE.
• Field mapper: Qeasy's field mapper automatically renames Kingdee fields like Number, Name, SETTLECATEGORY to generic names (settlement_type_code, etc.), and supports one-click triplet (Id/Name/Number) extraction.
• Incremental variable: platform provides built-in {{LAST_SYNC_TIME|datetime}}; initial sync starts at zero and auto-advances.
• Triggers & scheduling: configure 1 8-22 * * * in the strategy scheduler; Qeasy handles checkpoint resume and retry on timeout.
• Target landing: this strategy is QUERY_ONLY, landing into the Qeasy data pool for downstream DingTalk subscription.

Cross-Project Practical Points

1. Use Number, not FNumber, as the key: ExecuteBillQuery returns field name Number; both id/number in metadata must point to Number—using FNumber breaks incremental matching.
2. Always use FModifyDate as incremental watermark: a common pitfall is using CreateDate, which misses subsequent modifications.
3. Filter disabled items: ForbidStatus='B' means disabled; downstream selectors and reimbursement flows must filter these out.
4. Use UseOrgId for multi-org visibility: CreateOrgId only shows the creator; cross-org permissions should rely on UseOrgId.
5. Don't try to delete system presets: IsSysPreset='Y' items (like cash) can only be disabled, not deleted, or business validation errors occur.
6. Audit triplet: prefer Name downstream: Qeasy's mapper can extract automatically, reducing redundant downstream fields.

Pitfall Recap

• Pitfall 1: FieldKeys not declared leads to empty field returns. Solution: explicitly list all needed fields (including Id/Name/Number suffixes) instead of relying on default full returns.
• Pitfall 2: FModifyDate timezone mismatch. Kingdee returns UTC+8 strings; downstream UTC parsing creates an 8-hour skew, causing missed incremental records. Always specify |datetime with locked timezone in Qeasy variable formatting.
• Pitfall 3: Note-type settlement missing FRECBILLTYPE. At one retail client, "Bank Acceptance Draft" had no note type, breaking note module linkage on payment docs—two days to locate.
• Pitfall 4: Default settlement being overwritten. Blindly overwriting downstream config when FISDEFAULT='Y' is disabled leaves downstream with no default. Safest approach: sync only enabled items; route default changes via a dedicated strategy.
• Pitfall 5: Modifications outside scheduling window are missed. With 1 8-22 * * * crontab, late-night edits wait until next-day 8 AM. Acceptable for low-frequency changes but must be documented in SLA.

When to Use

Suitable for Kingdee Cloud + DingTalk (or heterogeneous system) integration requiring downstream payment selection, reimbursement approval, and master data sync. Not suitable for bidirectional sync, deeply customized fields, or non-Kingdee settlement systems—those cases should use custom connectors or document mapping strategies.