Integration Solution for Jushuitan and Kingdee YXC: 8 Strategies for Bidirectional Order and Inventory Sync

Scenario and Value

E-commerce retailers commonly use Jushuitan to manage online stores and Kingdee YXC (Cloud Starry) to manage financials and inventory. The data silos between these two systems typically lead to three pain points: sales outbound orders must be re-entered on the finance side, inventory quantities drift between the two systems, and there is no unified alerting when exceptions occur. This article presents a generic bidirectional integration solution covering 8 strategies, 4 master-data queries, and 1 WeCom alerting channel. The integration platform (middleware) handles code mapping, field transformation, retry logic, and scheduling, forming a closed loop around "sales orders" and "real-time inventory" across the two systems.

The core value: use the sales outbound order as the main line to resolve delayed bookkeeping on the finance side, write inventory back as stocktaking documents to reconcile physical vs. book counts, and visualize all strategy execution status through a unified alerting channel. The solution is platform-agnostic and works with most ETL or data-sync products.

Integration Architecture and Data Flow

The architecture has four layers. The source layer includes Jushuitan (supporting both Qimen and non-Qimen interface modes) and Kingdee YXC V2. The middleware layer is the integration platform, responsible for code mapping, field transformation, retry handling, and scheduling. The target layer varies by direction—it includes both Kingdee YXC and Jushuitan depending on the data flow. The notification layer is WeCom, used to push exception status.

Four data flows exist:

1. Jushuitan → Kingdee YXC: Qimen sales outbound orders (jushuitan.saleout.list.query) and non-Qimen sales outbound orders (/open/orders/out/simple/query) are pulled incrementally and written to the Kingdee sales outbound interface (/jdy/v2/scm/sal_out_bound).
2. Kingdee YXC → Jushuitan: Real-time inventory (/jdy/v2/scm/inventory) is split by warehouse and written to Jushuitan stocktaking documents (/open/jushuitan/inventoryv2/upload), using type=check for full overwrite.
3. Kingdee YXC → Integration Platform: Four types of master data (material, warehouse, logistics company, account) are pulled into the middleware in QUERY_ONLY mode for code mapping and business validation.
4. Integration Platform → WeCom: Periodically query StrategyErrorDetail and push failure details to the group bot.

Regarding execution dependencies, master-data queries (strategies 1-4) must run before business document sync to provide mappings for shop→customer, SKU→material, and warehouse codes. The WeCom alerting strategy can be scheduled independently.

Interface List

Note: A=Jushuitan, B=Kingdee YXC V2

Implementation Key Points

The dual-path sales outbound order sync (Qimen and non-Qimen) is the main strategy. The two source interfaces, incremental fields (start_time/end_time vs modified_begin/modified_end), and date field priorities (pay_date vs io_date) differ, but the target document structure is identical, so field mappings can be reused. Key handling: shop_id→customer_number and sku_id→material_number code mappings; concatenate so_id+remark as the document remark for traceability; fix delivery_type_id=6 as express delivery; set bill_source=ISV to identify the data source.

Inventory write-back to stocktaking documents must be split and submitted by stock_number dimension, so a single warehouse failure does not affect others. When a material cannot be mapped to sku_id, skip that line item and trigger an alert rather than failing the whole batch. The so_id field uses a random placeholder to avoid conflicts with online order numbers.

Master-data queries uniformly use millisecond timestamps (LAST_SYNC_TIME appended with three zeros) for incremental filtering, supporting modify_start_time/modify_end_time. Material queries must call the detail interface (/jdy/v2/bd/material_detail) to retrieve extended fields such as price.

Exception handling falls into four categories: network errors (timeout, 5xx) use exponential backoff retry up to 3 times; rate limiting (429) uses fixed-interval retry up to 5 times; business validation failures (4xx) are not retried but logged with source-table status updates; missing code mappings are not retried but trigger immediate alerts. All failures are pushed through the WeCom channel.

Best Practices

1. Phased scheduling: Run master-data strategies (1-4) in parallel first, then business document strategies (5, 6), then inventory-to-stocktaking (7). Run the alerting strategy (8) independently at high frequency.
2. Code unification beats mapping maintenance: Where business allows, align Jushuitan SKU codes with Kingdee material codes to significantly reduce mapping-table maintenance.
3. Separate initialization from daily run: Use full mode (remove time filters) for initial deployment, then switch to incremental for daily operations. Full re-syncs should run as separate tasks, not mixed with high-frequency scheduling.
4. Idempotent writes to prevent duplicates: Use idCheck or the source document number as a unique key for deduplication to avoid duplicate documents caused by retries and concurrency.
5. Tiered alerting thresholds: A single-strategy failure rate >10% triggers a warning; ≥3 consecutive failures or API availability <95% triggers a critical alert; business document delay exceeding 2 scheduling cycles immediately notifies operations.
6. Sensitive information masking: Solution IDs, tenant IDs, and API keys should not be hard-coded in sync logic; they should be injected through the platform's configuration center and stored encrypted.