Writing Back Sales Logistics Tracking Numbers to Kingdee Miscellaneous Issue Vouchers: A Closed-Loop Sync Practical Guide on Qeasy

What This Strategy Solves

In supply chain integration, the step most often underestimated is logistics write-back. In one of our projects at a retail client, the team first pushed Kingdee offline miscellaneous issue vouchers into JKY sales orders, and the warehouse only generated the carrier and tracking number after shipment in JKY WMS. If that information never returns to Kingdee, financial reconciliation and platform reconciliation both stall.

This strategy closes that loop. Once JKY WMS completes shipping, it writes back the carrier name, tracking number, and platform order number to the header of the existing Kingdee Cloud miscellaneous issue voucher. It does not create new vouchers, does not modify entity lines, and only updates logistics-related fields. It is a classic "narrow but stable" synchronization pattern.

Data Flow and Field Mapping

The overall flow is "JKY Qimen -> Qeasy middleware -> Kingdee Cloud". The source side pulls incremental transaction data through jackyun.tradenotsensitiveinfos.list.get, while the target side uses batchSave (FormId: STK_MisDelivery, Operation: BatchSave) to precisely update existing vouchers by FID.

Key field mapping (source -> target):

The most critical row is sellerMemo -> FID: when the Kingdee -> JKY strategy runs, Kingdee's FBillNo is written into JKY's sellerMemo; on write-back, _mongoQuery searches the MongoDB mirror for records where content.FBillNo equals {{sellerMemo}}, retrieves content.FID, and precisely targets the Kingdee voucher to update.

How to Configure It on Qeasy

When configuring this strategy on the Qeasy Data Integration Platform, there are three core points:

1. Source collector: Use the "JKY Qimen" connector, select the API jackyun.tradenotsensitiveinfos.list.get, and run incremental queries by startModified / endModified, with the time window automatically stitched using {{LAST_SYNC_TIME|datetime}} to {{CURRENT_TIME|datetime}}. The tradeTypeList covers multiple transaction types and isDelete=0 excludes deleted orders.
2. Middleware lookup: On the target field "FID", configure a TRANSFORM expression that calls _mongoQuery to query the upstream strategy's mirror table and reverse-lookup FID by sellerMemo. This is the "centralized encoding mapping" pattern Qeasy customers commonly adopt—cross-strategy association keys are uniformly persisted in MongoDB mirror tables rather than hardcoded into each strategy.
3. Target executor: Use the "Kingdee Cloud" connector, select the batchSave API, and explicitly declare in NeedUpDateFields that only header fields like FID, F_Platform_order_number, F_EXPRESS_COMPANY, F_Express_tracking_number, F_Platform_order_number2 are updated. Set IsAutoSubmitAndAudit=false and IsDeleteEntry=false to preserve manual audit and entity integrity.

Implementation Steps

Rolling it out in staged scheduling is the safest approach:

• Stage 1 – Incremental starting point: First, set startModified to an explicit starting point (for example, midnight of the previous day) and manually trigger one full backfill to confirm that sellerMemo and FBillNo can correctly cross-query each other. This is the cold-start step and must be manually verified.
• Stage 2 – Full-volume trigger: If existing Kingdee miscellaneous issue vouchers have no logistics information for the past few months, it is recommended to run a full-volume backfill during off-peak hours to ensure historical vouchers also get logisticName / mainPostid. The Qeasy platform supports time-window batch backtracking.
• Stage 3 – Scheduling frequency: Both the source and the target are set to "every 7 minutes, 7:00-22:00", the source uses 1-59/7 7-22 * * *, and the target is staggered by 2 minutes with 3-59/7 7-22 * * * to avoid both ends competing for the same window. The schedule pauses at night and naturally stitches at {{LAST_SYNC_TIME}} in the morning, which is a common incremental-plus-full-volume dual-track approach.
• Stage 4 – Monitoring and rerun: Log every record on Qeasy, focusing on _mongoQuery hit counts and batchSave return codes. A hit count of zero usually means the association key was not written, and the upstream strategy needs to be investigated.

Pitfalls and Lessons Learned

1. Association key not written, write-back fails everywhere: If the Kingdee -> JKY strategy forgets to write FBillNo into sellerMemo, this strategy's _mongoQuery will never find an FID, and the symptom is "vouchers are not updated". The safe practice is to make writing the association key a mandatory mapping node in the upstream strategy and add unit tests for it.
2. Treating the entire voucher as new creation: A typical mistake is using save instead of batchSave + NeedUpDateFields, which can rebuild entity lines or even duplicate vouchers. It is essential to adopt the "header/body staged" pattern here—this strategy only updates the header, IsDeleteEntry=false, and entity lines are left completely untouched.
3. Incomplete interface structure rejected by Kingdee: Kingdee's batchSave strictly requires that the request body contains FEntity. Even though we do not update the entity, we must still pass the entire goodsDetail array as FEntity, otherwise the API will return a structure error.
4. Scheduling window misaligned with business hours: Setting up 24-hour polling may seem safe, but since JKY WMS does not ship at night, it generates a lot of empty runs; setting 7:00-22:00 fits the actual business and reduces meaningless calls.
5. NeedUpDateFields misconfigured: Without explicitly declaring update fields, Kingdee may default to updating the entire model and clear unrelated fields. It is recommended to make the allowed-update fields a whitelist on Qeasy and review it every time the strategy is modified.

Suitable and Unsuitable Scenarios

Suitable: Offline sales pipelines where Kingdee and JKY already have basic vouchers integrated and the WMS shipment logistics information needs to be written back to the Kingdee header; and any narrow update scenario where only headers are updated across systems without touching entity lines.

Not suitable: Scenarios that require creating new Kingdee miscellaneous issue vouchers (use the forward strategy "Kingdee - Miscellaneous Issue Voucher -> JKY - Sales Order" instead); and system combinations where the source side does not have sellerMemo and therefore cannot establish a reverse association key.