Kingdee Cloud Settlement Type Query Interface Handbook: ExecuteBillQuery Field Mapping & Incremental Sync Guide

What This Interface Solves

In Kingdee-to-DingTalk integration scenarios, settlement type is a foundational master data that touches collections, payments, expense reimbursement, and approval flows. By pulling Kingdee Cloud's BD_SETTLETYPE table via ExecuteBillQuery, you establish a unified, trustworthy, and traceable payment dictionary. Downstream business documents can then reference a single source of truth for "select settlement type," avoiding reconciliation headaches caused by inconsistent definitions on both sides.

API Capability Overview

• Protocol: Kingdee Cloud WebAPI, ExecuteBillQuery, FormId BD_SETTLETYPE, HTTP POST.
• Authentication: Standard Kingdee third-party login (typically userName + password + appId + appSecret or OAuth-derived access_token), encapsulated by the Qeasy adapter so you don't handcraft tokens.
• Request structure: FormId, FieldKeys, FilterString, Limit, StartRow, OrderString.
• Response structure: JSON array, each row keyed by FieldKey; the primary key and code both surface as Number.
• Pagination: Limit + StartRow based; recommended page size 2000-5000 rows—larger pages risk Kingdee-side timeouts.
• Incremental mode: FilterString: FModifyDate>='{{LAST_SYNC_TIME|datetime}}'; crontab typically 1 8-22 * * * for high-frequency refresh during business hours.
• Strategy type: QUERY_ONLY—never writes back to a target system.

Typical Field Mapping

Configuring It on Qeasy

On the Qeasy Data Integration Platform, "Query Kingdee Settlement Type" is typically packaged as a query template within the Kingdee Cloud adapter:

1. Data source setup: Provide the Kingdee tenant endpoint, account set ID, and app secret. The adapter handles token lifecycle automatically.
2. Form selection: Pick BD_SETTLETYPE from the dropdown; the platform preloads the standard field set for that form.
3. Field mapper: In Qeasy's visual mapping canvas, drag Kingdee fields like Number/Name/SETTLECATEGORY/PAYTYPE/FModifyDate to your target schema. The built-in id/number merge strategy automatically uses Number as both primary key and code.
4. Incremental configuration: In the FilterString editor, reference the built-in variable {{LAST_SYNC_TIME}}; the first run is full sync, subsequent runs are incremental—seamless.
5. Scheduler: Configure crontab 1 8-22 * * * visually; the platform auto-retries with backoff within the window.
6. Target write: Because the strategy is QUERY_ONLY, data lands in the Qeasy master data pool, where other strategies (DingTalk approval, sales order, etc.) can reference it.

Cross-Project Best Practices

1. Confirm Number's dual identity: Across multiple client projects we consistently map Number to both id and number. Never use Name as a cross-system key—same-name-different-code is extremely common.
2. Unify FModifyDate as the incremental anchor: CreateDate can change during auditing or backfilling, but FModifyDate is the only reliable anchor for incremental sync.
3. Sync the disabled state downstream: When ForbidStatus='B', the DingTalk selector must hide the entry; otherwise users will pick a disabled settlement type and downstream document generation will fail.
4. Don't store only the ID for multi-org fields: Always carry the full Id/Name/Number trio for CreateOrgId and UseOrgId; later filtering or display becomes trivial.
5. High frequency during business hours, low at night: The crontab 1 8-22 * * * is field-tested—settlement types rarely change overnight, so reducing frequency saves quota.
6. Two-step full-then-incremental: The first run must use an empty FilterString to pull everything and reconcile the row count with Kingdee; only then switch to incremental. This pattern is easier to debug.

Pitfall Replays

1. FilterString time format with T and Z: Kingdee's FModifyDate comparison requires yyyy-MM-dd HH:mm:ss. Using ISO strings returns empty or full data—this is where projects commonly trip. The safe approach is to format explicitly within Qeasy's FilterString expression.
2. Mistakenly deleting system-preset records: Records with IsSysPreset='1' cannot be deleted, only disabled. If the downstream logic is "sync and delete on missing," it will error out. Add a skip rule in the mapper.
3. Pagination Limit too large causes timeout: Setting Limit to 10000 triggers a 60-second timeout on the Kingdee side and returns an empty array—easy to mistake for "no data." In real projects, keeping Limit at or below 3000 is safest.
4. Incremental data loss: One project used UTC for LAST_SYNC_TIME while Kingdee uses UTC+8, so changes during early morning were missed. Always align Qeasy's timezone configuration with Kingdee.
5. Same-named settlement types confuse users: Within the same enterprise, "Cash" and "Cash (Reserve)" share similar Names but different Numbers. Downstream displays should append the Number suffix for unambiguous troubleshooting.

When to Use

This interface fits scenarios where Kingdee is the single source of truth for settlement types and you need to push that dictionary to downstream systems like DingTalk, or unify payment semantics across multiple business documents. If your business only uses cash and you don't need cross-system coordination, hardcoding is simpler and this interface is unnecessary.