Authoritative Tutorial on Kingdee Cloud Skylight Supplier List Query Interface (ExecuteBillQuery / BD_Supplier)
What Problem Does This Interface Solve
In real-world scenarios of integrating Kingdee Cloud Skylight (Kingdee Cloud) with DingTalk, SRM, and expense control systems, 'supplier master data' is the source of all procurement, payment, and reconciliation flows. We need to stably pull supplier master data (code, name, organization, settlement, tax, classification, etc.) from the BD_Supplier table in Kingdee in an incremental manner, serving as the master data source or mapping baseline for downstream systems. This interface uses Kingdee WebAPI's executeBillQuery, incrementally syncs by audit date (FAuditDate), and lands as a data object reusable by any downstream.
Interface Capability Overview
- Authentication: Standard Kingdee Cloud WebAPI signature (API Key / Secret + Account Set + User), obtained through third-party application registration.
- Request Method: POST, Form ID is
BD_Supplier(Supplier Master Data Table). - Request Body Key Fields: FormId, FieldKeys (field selection), FilterString (filter condition, e.g.
FAuditDate>='{{LAST_SYNC_TIME|dateTime}}'), Limit, StartRow, OrderString. - Response Structure: Standard JSON containing multiple records, each record has field names as keys and string values (note: even numeric/date fields are returned as strings).
- Pagination Mode: Offset pagination based on StartRow + Limit, recommended Limit ≤ 2000, need to loop until returned rows < Limit.
- Incremental Mode: Uses audit date (FAuditDate) as incremental cursor, LAST_SYNC_TIME takes last maximum audit time, scheduled daily at 3:34 (
34 3 * * *). - Strategy Type: Pure QUERY, read-only on Kingdee, no write.
Typical Field Mappings
| Field Name | Type | Meaning | Practical Notes |
|---|---|---|---|
| FSupplierId | string | Supplier Primary Key | metadata.id must be configured with this field, unique anchor for cross-system matching |
| FNumber | string | Supplier Code | Business code, recommended as matching key with downstream systems (DingTalk/SRM) |
| FName | string | Supplier Name | Display name, may contain full-width/half-width differences, unify trim when cleaning |
| FCreateOrgId_FNumber | string | Create Org Code | Required in multi-org scenarios, otherwise ownership org is lost |
| FUseOrgId_FNumber | string | Use Org Code | Multi-org supplier visibility range, strict validation in cross-org integration |
| FCorrespondOrgId_FNumber | string | Correspond Org Code | For cross-org mapping, often overlooked |
| FAddress | string | Contact Address | Multi-line text, need to preserve line breaks |
| FRegisterAddress | string | Registered Address | Stored separately from contact address, used for compliance auditing |
| FZip | string | Postal Code | String format, avoid forced conversion to integer losing leading zeros |
| FPayCurrencyId_FNumber | string | Settlement Currency Code | Required for cross-currency integration |
| FSettleTypeId_FNumber | string | Settlement Method Code | Wire transfer/Acceptance/Credit etc. |
| FPayCondition_FNumber | string | Payment Term Code | Monthly settlement/Cash on delivery etc. |
| FChargeId_FNumber | string | Charge Party Code | Actual legal entity receiving payment |
| FTaxType_FNumber | string | Tax Classification Code | General taxpayer/Small-scale |
| FTaxRegisterCode | string | Tax Registration Number | Old tax number, may be empty |
| FSOCIALCRECODE | string | Unified Social Credit Code | 18 digits, most authoritative master data identifier, takes precedence cross-system |
| FRegisterCode | string | Business Registration Number | Business license number |
| FRegisterFund | string | Registered Capital (10K yuan) | Decimal, transmitted as string, use toDecimal when consuming |
| FFoundDate | string | Establishment Date | Date string, format yyyy-MM-dd |
| FLegalPerson | string | Legal Representative | Name, need desensitization for compliance export |
| FTendPermit | string | Production Operation License Number | Required for special industries |
| FSupplierClassify_FNumber | string | Supplier Category Code | Hierarchical management |
| FSupplyClassify | string | Supply Category | Material/Service |
| FSupplierGrade_FNumber | string | Supplier Grade (A/B/C) | Procurement strategy basis |
| FGroup | string | Supplier Group | Custom grouping |
| FCompanyNature_FNumber | string | Company Nature | State-owned/Private etc. |
| FCompanyScale_FNumber | string | Company Scale | Large/Medium/Small |
| FTrade_FNumber | string | Industry Code | Industry classification |
| FTendType_FNumber | string | Business Type | Production/Trade/Service |
| FInvoiceType | string | Invoice Type | VAT special/Ordinary |
| FTaxRateId_FNumber | string | Default Tax Rate Code | Procurement default tax rate |
| FPRICELISTID_FNumber | string | Default Price List Code | Procurement price source |
| FDiscountListId_FNumber | string | Default Discount List Code | Default discount |
| FMinPOValue | string | Minimum Order Quantity | Decimal, need toDecimal |
| FPayAdvanceAmount | string | Single Prepayment Limit | Decimal, need toDecimal |
| FProviderId_FNumber | string | Supplier Party Code | Actual supplying entity |
| FWipStockId_FNumber | string | Default WIP Warehouse | Work-in-process warehouse |
| FVmiBusiness | string | VMI Enabled | Checkbox, Y/N |
| FVmiStockId_FNumber | string | VMI Warehouse Code | VMI-dedicated warehouse |
| FDeptId_FNumber | string | Responsible Dept Code | Business owning department |
| FStaffId_FNumber | string | Responsible Staff Code | Businessperson |
| FNeedConfirm | string | Need Confirmation | Checkbox, Y/N |
| FBusinessStatus | string | Business Status | Draft/Audited etc. |
| FFreezeLimit | string | Freeze Scope | Multi-select dropdown, comma-separated string |
| FFreezeDate | string | Freeze Date | Date string |
| FStartDate / FEndDate | string | Effective/Expiry Date | Master data validity, recommend validation when integrating |
| FShortName | string | Short Name | List display |
| FDescription | string | Description | Multi-line text |
| FWebSite | string | Company Website | Multi-line text, may have multiple |
| FCountry_FNumber / FProvincial_FNumber / FLanguage_FNumber | string | Country/Region/Language Code | Reference auxiliary data |
| FParentSupplierId_FNumber | string | Parent Company/Superior Supplier | Group structure |
| FCustomerId_FNumber | string | Corresponding Customer Code | Same legal entity corresponding customer |
| FSettleId_FNumber | string | Settle Party Code | Actual settlement entity |
| FFinanceDesc | string | Finance Description | Multi-line text |
How to Configure on Qeasy Cloud Data Integration
In the Qeasy Cloud Data Integration platform, we typically use the 'Kingdee Cloud Skylight Adapter + Data Query Strategy' to encapsulate this interface:
- Data Source Configuration: Create a Kingdee Cloud Skylight connection in Qeasy's 'Data Source Management', fill in the account set identifier, application ID, API Key/Secret, user account; Qeasy has built-in signature generation logic, no manual signature calculation needed.
- Interface Selection: Qeasy's adapter abstracts executeBillQuery into a visual 'Form Query' node, just select FormId =
BD_Supplier, check the required FieldKeys from the field list, and the platform will automatically assemble the request body. - Incremental Configuration: In Qeasy's strategy editor, FilterString uses template syntax
FAuditDate>='{{LAST_SYNC_TIME|dateTime}}', the platform has built-in LAST_SYNC_TIME variable persistence, first full sync then all subsequent incremental syncs are automatic. - Field Mapper: Qeasy's field mapper automatically expands
F*_FNumbertype associated fields into 'code + name' dual format, downstream can directly use code for matching and name for display. - Pagination and Rate Limiting: Qeasy defaults to Limit=2000 with automatic pagination loops; when encountering Kingdee-side 429/timeout, the platform performs exponential backoff retry and writes each page into checkpoints, supporting resume from breakpoint after interruption.
- Writing to Downstream: This strategy is QUERY, results can be directly written to Qeasy's 'Data Mart' for subscription by DingTalk, SRM, BI and other multi-targets; can also serve as master data source for subsequent SYNC strategies.
Cross-Schemes Practical Points
- Prioritize FSOCIALCRECODE for cross-system unique key: In multiple customer schemes, as long as the downstream system supports it, the unified social credit code is more stable than FNumber (code changes don't affect it).
- Don't mix FNumber and FSupplierId: FSupplierId is the database primary key (may duplicate across account sets), FNumber is the business code; always use FNumber for downstream matching.
- Multi-org triplet must be fully fetched: FCreateOrgId_FNumber / FUseOrgId_FNumber / FCorrespondOrgId_FNumber are all required, otherwise cross-org procurement loses ownership.
- Finance settlement fields as a separate group: FPayCurrencyId / FSettleTypeId / FPayCondition / FChargeId / FTaxRateId this group of fields must land in downstream expense control, SRM, recommend checking as a FieldKeys subset to avoid missing fields.
- Date and numeric fields returned as strings: Kingdee interface uniformly returns dates and decimals as strings, must toDate / toDecimal when landing, otherwise downstream Java/JS forced conversion errors.
- Freeze and validity fields need business validation: FBusinessStatus / FFreezeLimit / FStartDate / FEndDate must be filtered when syncing to DingTalk or downstream, otherwise frozen or expired suppliers will be pushed downstream.
Pitfall Retrospective
- Pitfall: Wrong field used in FilterString causing data loss. The safe approach is audit date (FAuditDate) rather than creation date or modification date, the latter loses data in un-audit/reject scenarios.
- Pitfall: Limit set too large causing Kingdee server truncation or timeout. Qeasy's default 2000 is verified across multiple customer stress tests, safe range is 1000-2000, exceeding 5000 is highly prone to timeout.
- Pitfall: F*_FNumber associated fields cannot get names. Kingdee only returns codes, names need to be separately cached or reverse-queried in downstream; Qeasy's field mapper can pull 'code + name' combination at once, but must check the corresponding auxiliary data FieldKey.
- Pitfall: Checkbox / multi-select dropdown return value format confusion. FNeedConfirm / FVmiBusiness are "true"/"false" or "Y"/"N", FFreezeLimit is comma-separated code string, downstream must parse as string, do not assume as array.
- Pitfall: Incremental cursor clock drift. LAST_SYNC_TIME must use the maximum FAuditDate + 1 second returned by Kingdee side, not local current time; otherwise data audited multiple times within the same day will be missed in sync.
When to Choose
Choose this interface when the integration scenario involves 'using Kingdee Cloud Skylight as the sole trusted source of supplier master data, distributing to DingTalk, SRM, expense control, BI and other downstream systems'; if downstream just occasionally queries a single supplier, directly calling Kingdee document interface is lighter. Note: this interface is for query only, no write to Kingdee, master data creation/modification still needs to go through the supplier save interface.