Sync Kingdee Sales Outbound to Business System Shipping Message: Single Strategy Tutorial

What This Strategy Solves

In a retail company, sales orders are created in the business system and pushed to Kingdee Cloud as sales orders. After the warehouse ships, sales outbound documents are generated in Kingdee with logistics company and tracking numbers recorded there. However, store staff and customer service need to see shipping status, which only lives in the business system. If logistics information stays only in Kingdee, end users cannot see it and the order status remains stuck at "pending shipment".

This strategy performs the "Kingdee → business system" write-back: it incrementally pulls outbound documents by approval time and writes the outbound number, logistics company, tracking number, and product details back to the sales order in the business system. In one go, shipping status, outbound details, and logistics tracking are all aligned, eliminating manual re-entry.

Data Flow and Field Mapping

Data Flow: Kingdee Cloud (SAL_OUTSTOCK) → Qeasy Data Integration Platform (grouping, mapping) → Business System (/Kingdee/UpdateSaleOrderLogistics)

The source uses Kingdee's executeBillQuery, filtered by FApproveDate>='{{LAST_SYNC_TIME}}' and FDocumentStatus='C', pulling only approved outbound documents within the incremental window. The returned structure is flat rows, each carrying both master and detail fields. The platform groups by FBillNo (outbound number), and each group generates one target request.

Master Field Mapping:

Detail Row Mapping: each productItems element references source detail fields via items.*, including FMaterialID_FNumber, FMaterialID_FName, FRealQty, FSerialNo, FCarryBillNo.

How to Configure in Qeasy

When implementing this strategy on the customer site, we mainly configure four parts:

1. Source Metadata: Select the Kingdee Cloud platform, QUERY effect, executeBillQuery API, number/id both set to FBillNo, idCheck=true. Check all request fields including FBillNo, FDate, FSoorDerno, FStockID_FNumber, F_WDZN__YSJ_Logcompany, F_WDZN__YSJ_Logbillno, and detail fields FMaterialID_FNumber, FMaterialID_FName, FRealQty, FSerialNo.

2. Target Metadata: Select the business system platform, EXECUTE effect, /Kingdee/UpdateSaleOrderLogistics, POST. Configure the value for each request field per the table above, logistics fields directly use {{...}} passthrough, and the value of productItems is items.

3. Mapping Relationships: Use Qeasy's "centralized encoding mapping management" to align F_WDZN__YSJ_Logcompany logistics company names with the business system dictionary. Material codes should be synchronized first through the "Material to Business System" strategy to ensure SKU consistency.

4. Scheduling: Source cron */10 7-22 * * * (every 10 minutes during business hours), target */10 * * * * (all day). This is a typical implementation of the "incremental and full dual-track" pattern.

Implementation Steps

In our projects, we usually divide this into three phases:

• Phase 1 · Incremental Starting Point: First run a historical full sync with FApproveDate >= '2025-01-01 00:00:00' to confirm order linkage, material mapping, and logistics fields can all be written back correctly. Qeasy supports phased header/body processing — get the header running first, then enable details.
• Phase 2 · Incremental Switch: Change the filter condition to FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and enable the cron. Observe for 24 hours first, confirm no duplicates and no missing records.
• Phase 3 · Routine Monitoring: Source every 10 minutes, target every 10 minutes, check pull count, write count, and failure retries from the Qeasy console. Set up separate alerts for missing logistics fields.

Lessons Learned

1. Broken Order Linkage: FSoorDerno does not match the business system order number, so logistics cannot be written. This is a common pitfall because the "Sales Order" must first be synced via the "Business System Sales Order to Kingdee" strategy, otherwise the outbound document has no FSoorDerno. The safe approach is to place this strategy's sequence after B and add depends_on validation.
2. Wrong Logistics Fields: Kingdee's standard fields FLogisticsNos and FLogComId coexist with extended fields F_WDZN__YSJ_*, but the business system only recognizes the extended fields. A typical mistake is to directly use standard field names, resulting in all empty write-backs.
3. Empty productItems Error: Some outbound documents have no detail rows, so items is an empty array and the business system API may reject it. The safe approach is to add a pre-check on the target side, or confirm with the business whether the API accepts empty arrays.
4. Flat Rows Not Grouped: executeBillQuery returns flat rows. Without grouping by FBillNo, each row becomes a request and the target API gets hammered. You must rely on the platform's default FBillNo grouping logic, not write your own loop.
5. Shipper Field Not Configured: outWareHousePerson target value is null. When the business really needs it, it is recommended to supplement from Kingdee extended fields or FLogComId association queries, rather than leaving it empty in production.

Applicable and Non-Applicable Scenarios

Applicable: Mid-to-large retail/distribution enterprises where the business system creates orders and Kingdee handles backend warehousing and finance, requiring real-time sync of shipping status and logistics tracking back to the frontend business system for store staff and customer service. Not Applicable: Pure financial accounting scenarios (no need to write back to business system), scenarios where logistics information is recorded in the business system rather than Kingdee, and projects where the prerequisite "Sales Order → Kingdee" sync has not been done first.