Qeasy Cloud
Get Started

Authoritative Tutorial on Kingdee Cloud Skylight Supplier List Query Interface (ExecuteBillQuery / BD_Supplier)

· Engineering Best Practices· 10 views· 6 min read
Kingdee CloudDingTalkexecuteBillQuery供应商主数据Data Integration轻易云Incremental Sync

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 NameTypeMeaningPractical Notes
FSupplierIdstringSupplier Primary Keymetadata.id must be configured with this field, unique anchor for cross-system matching
FNumberstringSupplier CodeBusiness code, recommended as matching key with downstream systems (DingTalk/SRM)
FNamestringSupplier NameDisplay name, may contain full-width/half-width differences, unify trim when cleaning
FCreateOrgId_FNumberstringCreate Org CodeRequired in multi-org scenarios, otherwise ownership org is lost
FUseOrgId_FNumberstringUse Org CodeMulti-org supplier visibility range, strict validation in cross-org integration
FCorrespondOrgId_FNumberstringCorrespond Org CodeFor cross-org mapping, often overlooked
FAddressstringContact AddressMulti-line text, need to preserve line breaks
FRegisterAddressstringRegistered AddressStored separately from contact address, used for compliance auditing
FZipstringPostal CodeString format, avoid forced conversion to integer losing leading zeros
FPayCurrencyId_FNumberstringSettlement Currency CodeRequired for cross-currency integration
FSettleTypeId_FNumberstringSettlement Method CodeWire transfer/Acceptance/Credit etc.
FPayCondition_FNumberstringPayment Term CodeMonthly settlement/Cash on delivery etc.
FChargeId_FNumberstringCharge Party CodeActual legal entity receiving payment
FTaxType_FNumberstringTax Classification CodeGeneral taxpayer/Small-scale
FTaxRegisterCodestringTax Registration NumberOld tax number, may be empty
FSOCIALCRECODEstringUnified Social Credit Code18 digits, most authoritative master data identifier, takes precedence cross-system
FRegisterCodestringBusiness Registration NumberBusiness license number
FRegisterFundstringRegistered Capital (10K yuan)Decimal, transmitted as string, use toDecimal when consuming
FFoundDatestringEstablishment DateDate string, format yyyy-MM-dd
FLegalPersonstringLegal RepresentativeName, need desensitization for compliance export
FTendPermitstringProduction Operation License NumberRequired for special industries
FSupplierClassify_FNumberstringSupplier Category CodeHierarchical management
FSupplyClassifystringSupply CategoryMaterial/Service
FSupplierGrade_FNumberstringSupplier Grade (A/B/C)Procurement strategy basis
FGroupstringSupplier GroupCustom grouping
FCompanyNature_FNumberstringCompany NatureState-owned/Private etc.
FCompanyScale_FNumberstringCompany ScaleLarge/Medium/Small
FTrade_FNumberstringIndustry CodeIndustry classification
FTendType_FNumberstringBusiness TypeProduction/Trade/Service
FInvoiceTypestringInvoice TypeVAT special/Ordinary
FTaxRateId_FNumberstringDefault Tax Rate CodeProcurement default tax rate
FPRICELISTID_FNumberstringDefault Price List CodeProcurement price source
FDiscountListId_FNumberstringDefault Discount List CodeDefault discount
FMinPOValuestringMinimum Order QuantityDecimal, need toDecimal
FPayAdvanceAmountstringSingle Prepayment LimitDecimal, need toDecimal
FProviderId_FNumberstringSupplier Party CodeActual supplying entity
FWipStockId_FNumberstringDefault WIP WarehouseWork-in-process warehouse
FVmiBusinessstringVMI EnabledCheckbox, Y/N
FVmiStockId_FNumberstringVMI Warehouse CodeVMI-dedicated warehouse
FDeptId_FNumberstringResponsible Dept CodeBusiness owning department
FStaffId_FNumberstringResponsible Staff CodeBusinessperson
FNeedConfirmstringNeed ConfirmationCheckbox, Y/N
FBusinessStatusstringBusiness StatusDraft/Audited etc.
FFreezeLimitstringFreeze ScopeMulti-select dropdown, comma-separated string
FFreezeDatestringFreeze DateDate string
FStartDate / FEndDatestringEffective/Expiry DateMaster data validity, recommend validation when integrating
FShortNamestringShort NameList display
FDescriptionstringDescriptionMulti-line text
FWebSitestringCompany WebsiteMulti-line text, may have multiple
FCountry_FNumber / FProvincial_FNumber / FLanguage_FNumberstringCountry/Region/Language CodeReference auxiliary data
FParentSupplierId_FNumberstringParent Company/Superior SupplierGroup structure
FCustomerId_FNumberstringCorresponding Customer CodeSame legal entity corresponding customer
FSettleId_FNumberstringSettle Party CodeActual settlement entity
FFinanceDescstringFinance DescriptionMulti-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:

  1. 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.
  2. 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.
  3. 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.
  4. Field Mapper: Qeasy's field mapper automatically expands F*_FNumber type associated fields into 'code + name' dual format, downstream can directly use code for matching and name for display.
  5. 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.
  6. 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

  1. 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).
  2. 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.
  3. Multi-org triplet must be fully fetched: FCreateOrgId_FNumber / FUseOrgId_FNumber / FCorrespondOrgId_FNumber are all required, otherwise cross-org procurement loses ownership.
  4. 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.
  5. 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.
  6. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/engineering/hb-p2-272-ok-f008

Comments