Qeasy Cloud
Get Started

Authoritative Tutorial on the Kingdee Cloud "Shop-Warehouse Mapping" Interface Field Handbook

· 陈洁琳· Engineering Best Practices· 26 views· 4 min read
MySQLKingdee CloudexecuteBillQuery网店仓库映射供应链集成字段手册轻易云

What This Interface Solves

In retail and e-commerce supply chain integration, the "shop ↔ warehouse" mapping is the foundation of orders, inventory, and shipments. Multiple customer projects point to the same pain point: Kingdee holds the master data, but the downstream e-commerce platform's warehouse codes must map one-to-one with Kingdee warehouses for correct routing. This interface uses executeBillQuery to pull shop master data and its mapping details with Kingdee/Wangdiantong (WDT) warehouses, serving as the configuration base for subsequent order, inventory, and inbound/outbound integrations.

Interface Capabilities Overview

  • Interface form: Kingdee Cloud generic query executeBillQuery, business object FormId is ECC_Shop (shop management document).
  • Authentication: Standard Kingdee Cloud identity auth (App ID / Secret / User authorization); Qeasy's Kingdee adapter centrally manages signing and sessions.
  • Request structure: FormId=ECC_Shop + FieldKeys (field list) + FilterString (commonly FMODIFYDATE>='2024-01-01 00:00:00' for incremental) + StartRow / Limit (pagination) + OrderString.
  • Response structure: Each record is a Map keyed by field names (with suffixes like _FNumber / _FName / _FEntryID for related fields); metadata.id in the outer wrapper maps to the primary key.
  • Pagination & incremental: Typical page Limit=1000~2000, sorted ascending by FMODIFYDATE; production environments commonly run every 5 minutes before business peaks (e.g., crontab */5 7-22 * * * observed in one retail deployment).

Typical Field Mapping

FieldTypeMeaningPractical Notes
FIDstringShop master internal key, unique within KingdeeOne of the incremental anchor keys
FNumberstringShop business codeUse FNumber for business reference; do not confuse with metadata.number
FNamestringShop display nameDisplay only; never use as a business primary key
FSaleOrgId_FNumberstringSales organization codeCritical for data isolation in multi-org scenarios
FCustomerId_FNumber / FCustomerId_FNamestringCustomer code / nameShop typically maps to one customer entity for AR and reconciliation
FStockOrgId_FNumberstringInventory organization codeDefines inventory availability scope
FShopStock_FEntryIDstringShop-stock entry line primary keyReal dedup key; only (FID, FShopStock_FEntryID) uniquely identifies one mapping
F_PBLH_WDTSTOCK_FNumber / _FNamestringWDT warehouse code / nameF_PBLH_ is a Kingdee extension-field prefix meaning the field is used in WDT docking
FStockId_FNumber / FStockId_FNamestringKingdee warehouse code / nameActual warehouse under the inventory org, the routing endpoint for orders and inventory

How to Configure on Qeasy

  • Kingdee adapter: Qeasy ships a built-in Kingdee Cloud connector that wraps signing, tenant switching, pagination, and retry for executeBillQuery. Business users only configure FormId and filter conditions.
  • Field mapper: When mapping to a MySQL shop_warehouse_mapping table, Qeasy's field mapper automatically splits _FNumber / _FName into separate code and name columns, avoiding manual SQL handling.
  • Incremental strategy: Combine "modified time + internal key dedup". Qeasy's scheduler caches the "last max FMODIFYDATE", supports one-click incremental, and avoids data loss across breakpoints.
  • Safety net: Enable Qeasy's "empty-response detection" before persisting each batch result to avoid silently treating a no-data response as success.

Cross-Project Practical Highlights

  1. The real dedup key is (FID, FShopStock_FEntryID): FID is only the shop master; one shop has multiple warehouse mappings, so using FID alone always duplicates.
  2. FNumber ≠ FName: In Kingdee's response metadata, the value of number is actually the name. This is the most common pitfall; always model as "FNumber = code, FName = name".
  3. Use FMODIFYDATE>= for incremental: Across multiple projects, using > alone loses records at day boundaries; the safe way is "last success time - 2 minutes" + >=, ordered by FMODIFYDATE, FID.
  4. F_PBLH_ prefix means extension field: Don't treat it as standard; it is usually maintained by secondary development or the docking party and changes more frequently than base data, requiring dedicated change monitoring.
  5. Recommended page size Limit=2000: 5000 occasionally causes OOM in large orgs; 2000 is the sweet spot.
  6. Always filter by FSaleOrgId in multi-org: Skipping the sales-org filter pulls shops from all organizations, creating compliance risks in group-level reporting.

Pitfall Recap

  • Pitfall 1: Storing FName as code. One retail customer's first version synced metadata.number as code, so the code column contained names, breaking all downstream order routing. Fix: Explicitly use FNumber as the code column and add a unique constraint.
  • Pitfall 2: Incremental data loss. Querying only FMODIFYDATE > now loses multiple records within the same second at minute boundaries. Fix: Fall back to >=, rewind 2 minutes, and order by FMODIFYDATE, FID with dedup.
  • Pitfall 3: One-to-many mappings flattened into JSON. Storing entry data as a single JSON column kills performance for inventory allocation later. Fix: Create a detail table in MySQL with a unique index on (FID, FShopStock_FEntryID), keeping row-based storage.
  • Pitfall 4: WDT warehouse code changed. When F_PBLH_WDTSTOCK_FNumber changes on the WDT side, historical Kingdee order references break. Fix: Persist both code and name, and alert on fuzzy name mismatches.
  • Pitfall 5: Schedule too aggressive, throttling Kingdee. Every 30 seconds triggered Kingdee rate limiting. Fix: Relax to */5 7-22 * * * and apply concurrency limits on the Qeasy side.

When to Use

Adopt this interface whenever you need "e-commerce shop ↔ ERP warehouse" mapping for routing orders, inventory, and shipments. Single-shop-single-warehouse or brand-new greenfield setups don't need it; but once multi-platform, multi-shop, multi-warehouse scenarios or legacy reconciliation are involved, this interface is the foundational query of the entire supply chain integration and should be prioritized first.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/engineering/hb-p2-017-9e15

Comments