Kingdee Cloud Skyline Supplier API Field Handbook: End-to-End Guide from Query to Activation
What This Interface Solves
In risk supplier management, suppliers flagged as "risky" have a 60–92 day activation window. If no approval arrives within 92 days, the system auto-disables them. The business needs to connect Kingdee Cloud Skyline supplier master data with DingTalk approval flow: during the window, a DingTalk bot sends reminders; once approved, the result flows back to Kingdee to perform activation and unbanning. This guide systematizes hands-on experience around the Kingdee supplier query/write APIs and DingTalk approval/bot APIs to cover this closed loop.
Interface Capability Overview
Authentication: Kingdee Cloud Skyline uses WebAPI auth (Login to obtain a token, then call Save/ExecuteOperation). DingTalk approvals and bots use the Open Platform AccessToken (exchange AppKey/AppSecret of an internal app).
Request/Response Structure: For Kingdee BD_Supplier, the query API takes FormId, FilterString, FieldKeys, Limit, etc. Batch writes use batchSave (JSONArray of model objects). For DingTalk, topapi/processinstance/get takes process_instance_id and returns a form value list; oToMessages/batchSend takes robotCode + userIds + msgKey + msgParam.
Pagination/Incremental Mode: Kingdee implements increment via FilterString with time window and organization constraints. DingTalk upstream pulls processInstanceId incrementally by start_time; this strategy fetches details one by one via process_instance_id_strategy, naturally supporting idempotent deduplication.
Typical Field Mapping
| Field Name | Type | Meaning | Practical Notes |
|---|---|---|---|
| FNumber / value | string | Supplier code (shared semantic key across source and target) | DingTalk approval form value maps 1:1 to Kingdee FNumber, used as the lookup key for FSupplierId |
| FSupplierId | string | Kingdee supplier internal ID | The real locator for write/unban operations, must be retrieved via _findCollection |
| F_PUROrgId | string | Ordering organization | Used to map DingTalk recipient userIds; case-when branches maintained in config layer |
| FCreateDate | date | Risk supplier creation date | Baseline for activation window calculation, used in DATEDIFF for remaining days |
| FAuditDate | date | Audit date | Display field in reminder body |
| FUseOrgId.fnumber | string | Usage organization | Hardcoded in FilterString (e.g., 'T00'), replace per actual org at implementation |
| FSupplierClassify.fnumber | string | Supplier classification | Fixed '03' for risky suppliers, mandatory filter |
| FDocumentStatus | string | Document status | 'C' means audited, filters out unaudited documents |
| FForbidStatus | string | Forbid status | 'A' means not forbidden |
| FormId | string | Business object form ID | Fixed 'BD_Supplier' for suppliers |
| Operation | string | Operation type | 'batchSave' for activation, 'Enable' for unbanning |
| IsVerifyBaseDataField | bool | Whether to validate base data | Recommend true to avoid dirty data writes |
| IsAutoSubmitAndAudit | bool | Whether to auto-submit and audit | Recommend false for activation, let humans trigger audit |
| robotCode | string | DingTalk bot code | Maintained in config layer, never hardcode in solution |
| msgKey | string | Message template key | Markdown template fixed as 'sampleMarkdown' |
| process_instance_id | string | DingTalk approval instance ID | Pre-fetched by upstream strategy, referenced as input here |
How to Configure on Qeasy
On the Qeasy Data Integration Platform, Kingdee Cloud Skyline uses the "Kingdee Cloud Skyline Adapter" and DingTalk uses the "DingTalk Open Platform Adapter". Kingdee side: the adapter wraps Login and token maintenance; in the field mapper, drag the DingTalk approval value into the "Supplier Hub Lookup" node, which auto-generates the _findCollection expression; for batch write, select the BD_Supplier batchSave model and the platform auto-fills FormId, IsVerifyBaseDataField, and other constants. DingTalk side: the adapter has built-in actions for topapi/processinstance/get and oToMessages/batchSend; approval detail can be enabled with one click as "fetch one by one by process_instance_id strategy"; msgParam for the reminder is assembled via CONCAT expressions, and the field mapper prompts date formatting functions for FCreateDate and FAuditDate. Scheduling: Qeasy's scheduler supports separate crontab for source and target, automatically handling dependencies and upstream/downstream order.
Cross-Solution Practical Highlights
- Decouple code from internal ID: DingTalk forms only carry business codes; the actual write to Kingdee relies on FSupplierId lookup. Do not try to use codes as primary keys directly.
- Two-phase reminder within the window: 60–80 days every Monday, 80–92 days every day. Different frequencies reduce noise while preventing missed activation in the late phase.
- Strictly separate activation and unbanning: After batchSave activation, leave at least 3 minutes before Enable unbanning; Kingdee's internal state machine does not allow concurrent operations.
- Hub lookup is the key junction: The supplier code → FSupplierId lookup hub is shared by multiple strategies; ensure hub data is refreshed daily.
- Increment relies on timestamp + business status dual filter: Kingdee FilterString should combine FCreateDate with FDocumentStatus='C' and FForbidStatus='A' to avoid duplicate pushes.
- Idempotency by approval instance ID: Strategy 1 and Strategy 4 share the same upstream processInstanceId list; the platform deduplicates by ID, so one approval cannot trigger two activations.
Pitfall Retrospective
- Supplier code not found in Kingdee:
_findCollectionreturns empty, causing activation and unbanning to fail. The safe approach is to set a threshold in the config layer: alert if more than 5 failures occur in a single run, and involve humans. - DingTalk rate limit 429: Batch-fetching approval details easily triggers it. Exponential backoff of 30s/60s/120s is not enough; recommend setting 429 retries separately to 5 times with 60s intervals.
- Misjudging activation window boundaries:
DATEDIFF(date(now()), date(FCreateDate))may include those just hitting 92 days during cross-day scheduling. Use FilterString strictly with "60–79 days ago" and "80–91 days ago" segments instead of relying on expression-side filtering. - Bot not receiving messages: An empty userIds list is a frequent cause. The org→user ID mapping table must update synchronously with org changes; the config layer should add version number checks.
- Batch write with IsVerifyBaseDataField=false: Some disable validation for convenience, causing dirty FSupplierId to land in the database and become unrecoverable, which actually costs more time to clean up. This is a common pitfall.
When to Use
Applicable to "master data lifecycle management with approval flow" scenarios, especially business objects with time-sensitive thresholds such as risk suppliers, trial customers, and temporary accounts. If the approval is fully handled within Kingdee, there is no need to introduce DingTalk; if it is one-way reminders only, use Kingdee's built-in workflow messages directly, no need to build dual-side integration.