Qeasy Cloud
Get Started

Wangdiantong & Kingdee Cloud Cosmic Supply Chain Integration: Authoritative Cross-Solution API Field Handbook

· 何海波· Engineering Best Practices· 19 views· 5 min read
WDTKingdee Cloud供应链集成Field Mapping轻易云库存对账

What This Interface Solves

There is a natural data silo between e-commerce OMS/WMS (Wangdiantong) and ERP (Kingdee Cloud Cosmic): master data, inventory movements, sales outbound/returns, and purchase receiving/returns are independently accumulated in both systems, causing reconciliation difficulties, inventory drift, and disconnects between purchasing and fulfillment. This article focuses on full-chain integration between the two systems, consolidating 27 strategies across five domains—master data, inventory, sales, purchasing, and returns—into a practical handbook so engineers can master all field meanings, mapping logic, and pitfalls in one read.

API Capability Overview

Authentication: Wangdiantong uses application-level appkey + sid signature; Kingdee Cloud Cosmic in private deployment typically uses account username/password + interface secret, with some scenarios requiring IP whitelist binding.

Request/Response Structure: Wangdiantong Open Platform is encapsulated in JSON-RPC style, with responses uniformly returning code/status/message/data four-segment format; Kingdee Cloud Cosmic is based on its proprietary form model, with header and line items (FEntity) organized in two layers, where FormId (e.g., SAL_OUTSTOCK, STK_TransferDirect) determines the target document type.

Pagination & Incremental Mode: Wangdiantong APIs generally support page_no/page_size pagination, with some (e.g., material, transfer) supporting start_time/end_time time-window increment; for Kingdee Cloud Cosmic, FMODIFYDATE is recommended as the incremental cursor—run full sync on first deployment, then increment.

Typical Field Mappings

Source Field (Example)Target Field (Example)TypeMeaningPractical Notes
Kingdee FNumberWangdiantong goods_no / spec_nostringMaterial/spec codeCode mapping table is the foundation for all downstream strategies—must sync before business documents
Kingdee FNameWangdiantong goods_name / spec_namestringNameMulti-language/special chars need escaping to avoid write failure
Kingdee FBARCODEWangdiantong barcodestringBarcodeMulti-barcode scenarios: split by spec_no
Wangdiantong order_noKingdee FBillNostringDocument No.Kingdee has rules on length and prefix; direct 1:1 write may fail validation
Wangdiantong consign_time / stockin_timeKingdee FDatedatetimeBusiness dateMind timezone (UTC+8) and string format conversion
Wangdiantong warehouse_noKingdee FStockOrgId / FStockIdstringWarehouse/OrgKingdee warehouse and org are two layers—org mapping must not be missed
Wangdiantong shop_noKingdee FSaleOrgId / FCustomerIDstringShop/CustomerB and E (supply platform) scenarios have different mapping rules—branch handling needed
Wangdiantong provider_noKingdee FSupplierId.FNumberstringSupplierSupplier master must be synced first, otherwise writes will be rejected
Wangdiantong spec_no / goods_noKingdee FMaterialId.FNumberstringMaterialLine items must be expanded by spec dimension, otherwise quantity aggregation misaligns
Wangdiantong num / goods_countKingdee FQty / FRealQtydecimalQuantityDecimal places consistent with base unit—never pass piece count directly
Wangdiantong sell_priceKingdee FPricedecimalUnit priceMind precision and tax fields; some scenarios need tax-inclusive/exclusive split
Wangdiantong logistics_noKingdee FCARRIAGENO / F_ZZZZ_WLDHstringLogistics No.Return orders typically use custom field F_ZZZZ_ prefix

How to Configure on Qeasy Cloud

In Qeasy Cloud Data Integration Platform, this dual-system integration is typically split into adapter + strategy orchestration layers. On Wangdiantong side, use the platform's built-in "Wangdiantong Open Platform Adapter"—just configure appkey/sid and sandbox/production; on Kingdee side, use "Kingdee Cloud Cosmic WebAPI Adapter", fill in the account address, user, secret, and select the target FormId.

Qeasy Cloud's Field Mapper automatically recognizes both schemas, making code mappings for material, customer, warehouse, and supplier visual configuration tables; for strategies like 6/7 (A/C channels) and 13/14 (B channel), 16/17 (E channel)—"same form, different filter conditions"—it is recommended to use the platform's strategy clone + filter condition override capability instead of duplicating the entire data flow. The incremental cursor (FMODIFYDATE / consign_time) can be directly configured as "fetch by field ascending" in Qeasy Cloud's Scheduler, and linked with the Alert Strategy (Strategy 11) to auto-push to WeCom/DingTalk on failure.

Cross-Solution Practical Points

  1. Master Data First: Code mapping tables for material, customer, supplier, and warehouse must be in place before all business documents, otherwise the remaining 26 strategies will fail due to missing FMaterialId.
  2. Bidirectional Transfer Symmetry: Wangdiantong's transfer outbound/inbound corresponds to Kingdee's stepped transfer out/in (Strategy 2/3); reverse Kingdee transfer in/out maps to Wangdiantong "Other Inbound/Outbound" business orders (Strategy 4/5)—don't mix document types.
  3. Same Outbound Order to Different Channels: The same Wangdiantong sales outbound may simultaneously route to A (OMS reconciliation), C (OMS consignment), B (no reconciliation), E (supply platform); field mappings are basically the same, with key differences in shop_no → FSaleOrgId/FCustomerID mapping table and FBillTypeID constant.
  4. Strong Purchase Chain Dependency: Kingdee receipt notice precedes purchase order (Strategy 18); purchase inbound must carry purchase_no to reverse-query upstream (Strategy 19), otherwise cannot post.
  5. Dual-Write Incremental Cursor: Wangdiantong uses consign_time, Kingdee uses FMODIFYDATE; both incremental time windows must leave a 5-10 minute buffer to prevent boundary data loss.
  6. Cache Code Mappings: In Qeasy Cloud, materialize material, warehouse, and supplier mapping relations into a dimension cache table, do a local join before document write—faster and can intercept unknown codes upfront.

Pitfall Retrospective

  • Pitfall 1: Material code 1:1 direct write, Kingdee FBillNo length exceeded. Kingdee has max length and prefix rules on document numbers—Wangdiantong's original order_no written directly will be rejected. The safe approach is to add a SUBSTRING transform function in Qeasy Cloud's field mapper and configure a default prefix.
  • Pitfall 2: Warehouse/Org Confusion. Kingdee's FStockOrgId (Org) and FStockId (Warehouse) are two layers—in real scenarios we've seen customers map warehouse_no directly to FStockOrgId, causing transfer orders to fail to find the org dimension. Correct approach: build two separate mapping tables.
  • Pitfall 3: Sales return order fails to link original order. Kingdee return orders typically need to link the original sales outbound; Wangdiantong's trade_no_list is a multi-value string that will error on direct write. Make good use of Qeasy Cloud's string processing functions (LEFT 40) to truncate and write to custom field F_ZZZZ_DDBH.
  • Pitfall 4: Incremental Data Loss. Incrementing only by consign_time, cross-day data is cut to the next day, causing that night's data to be missed. Safe approach: use consign_time + 5 minutes sliding window, and use document number for idempotent deduplication.
  • Pitfall 5: Purchase inbound has no source document link. If Wangdiantong's purchase inbound doesn't carry purchase_no, Kingdee will reject it because it cannot link to the upstream purchase order. Be sure to write purchase_no as a join key in line items within the strategy.

When to Use

Suitable for mid-to-large retail/e-commerce enterprises requiring full-chain supply chain integration between Wangdiantong (OMS/WMS) and Kingdee Cloud Cosmic (ERP), covering master data sync, inventory reconciliation, sales outbound/return, and purchase receiving/return. Not for pure offline ERP, pure financial reconciliation, or simple point-query integrations (e.g., inventory-only check).

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/engineering/hb-p6-139-6107-bba5

Comments