Authoritative Tutorial on the Kingdee Cloud "Shop-Warehouse Mapping" Interface Field Handbook
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 isECC_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(commonlyFMODIFYDATE>='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/_FEntryIDfor related fields);metadata.idin the outer wrapper maps to the primary key. - Pagination & incremental: Typical page
Limit=1000~2000, sorted ascending byFMODIFYDATE; production environments commonly run every 5 minutes before business peaks (e.g., crontab*/5 7-22 * * *observed in one retail deployment).
Typical Field Mapping
| Field | Type | Meaning | Practical Notes |
|---|---|---|---|
| FID | string | Shop master internal key, unique within Kingdee | One of the incremental anchor keys |
| FNumber | string | Shop business code | Use FNumber for business reference; do not confuse with metadata.number |
| FName | string | Shop display name | Display only; never use as a business primary key |
| FSaleOrgId_FNumber | string | Sales organization code | Critical for data isolation in multi-org scenarios |
| FCustomerId_FNumber / FCustomerId_FName | string | Customer code / name | Shop typically maps to one customer entity for AR and reconciliation |
| FStockOrgId_FNumber | string | Inventory organization code | Defines inventory availability scope |
| FShopStock_FEntryID | string | Shop-stock entry line primary key | Real dedup key; only (FID, FShopStock_FEntryID) uniquely identifies one mapping |
| F_PBLH_WDTSTOCK_FNumber / _FName | string | WDT warehouse code / name | F_PBLH_ is a Kingdee extension-field prefix meaning the field is used in WDT docking |
| FStockId_FNumber / FStockId_FName | string | Kingdee warehouse code / name | Actual 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_mappingtable, Qeasy's field mapper automatically splits_FNumber/_FNameinto 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
- The real dedup key is
(FID, FShopStock_FEntryID):FIDis only the shop master; one shop has multiple warehouse mappings, so usingFIDalone always duplicates. FNumber≠FName: In Kingdee's response metadata, the value ofnumberis actually the name. This is the most common pitfall; always model as "FNumber= code,FName= name".- Use
FMODIFYDATE>=for incremental: Across multiple projects, using>alone loses records at day boundaries; the safe way is "last success time - 2 minutes" +>=, ordered byFMODIFYDATE, FID. 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.- Recommended page size
Limit=2000: 5000 occasionally causes OOM in large orgs; 2000 is the sweet spot. - Always filter by
FSaleOrgIdin multi-org: Skipping the sales-org filter pulls shops from all organizations, creating compliance risks in group-level reporting.
Pitfall Recap
- Pitfall 1: Storing
FNameas code. One retail customer's first version syncedmetadata.numberas code, so the code column contained names, breaking all downstream order routing. Fix: Explicitly useFNumberas the code column and add a unique constraint. - Pitfall 2: Incremental data loss. Querying only
FMODIFYDATE > nowloses multiple records within the same second at minute boundaries. Fix: Fall back to>=, rewind 2 minutes, and order byFMODIFYDATE, FIDwith 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_FNumberchanges 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.