Kingdee Receipt Bill to Collection Record Sync: A Single-Strategy Integration Tutorial

What This Strategy Solves

For retail/distribution companies where the finance system runs on Kingdee Cosmic and the business front-end uses a self-developed or third-party platform for order and collection reconciliation, approved receipt bills in Kingdee need to be written line-by-line into the business system's bank collection records for reconciliation, write-off, and voucher generation. This strategy handles the one-way incremental sync of "approved receipt bill → business system collection detail." It looks simple, but receipt bills have a master-detail structure while the target API is a flat single-record write, so encoding concatenation, incremental starting points, and detail-row iteration are common pitfalls.

Data Flow and Field Mapping

Data flows from Kingdee Cosmic to the business system, passing through the Qeasy data integration platform's visual orchestration and transformation layer. The source pulls approved bills incrementally by FApproveDate, and the target writes one record per detail line by calling the write API.

Core field mapping:

The source receipt bill is a master-detail structure, while the target API receives one flat record per call. Therefore, detail lines must be iterated, with master-table fields (FBillNo, FID, FDATE, FSETTLENO, FCONTACTUNIT_Fname) repeated on every detail row.

How to Configure in Qeasy

In the Qeasy data integration platform, this strategy is split into three stages: Source Query → Transform → Target Write.

• Source (QUERY): Select Kingdee Cosmic's executeBillQuery, set the form to AR_RECEIVEBILL, and explicitly list both master and detail fields (including _D-suffixed detail fields) in FieldKeys. Fix FilterString to: FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FDocumentStatus='C' to only pull approved bills.
• Target (EXECUTE): Select the business system's /Kingdee/UpdateBankPayBackInfo, leave number empty or set it to fBussinessOrderNo for idempotent deduplication.
• Mapping Layer: In Qeasy's field mapping canvas, use a "string concatenation" transformer for fBussinessOrderNo to write {{FBillNo}}-{{FID}}. Constant fields (fbookedType, fCreateOrgName, customerFbankId) are filled with fixed values directly. A common pattern Qeasy customers adopt is centralized encoding mapping management: all FBillNo+FID-style unique key concatenations are maintained in a single mapping table, making rule changes easier later.

Implementation Steps

Phased scheduling is critical to whether this strategy runs stably.

1. Incremental Starting Point: When going live for the first time, don't use FApproveDate>=some historical date to run a massive batch. A safe approach is to manually set LAST_SYNC_TIME to midnight of the launch day so only that day's data is pulled; historical data is backfilled via a separate full-trigger run.
2. Full Trigger: Use Qeasy's "full rerun" feature to backfill historical approved bills, batching by approval date (e.g., monthly batches) to avoid overwhelming the source executeBillQuery with tens of thousands of records at once.
3. Schedule Frequency: The source is recommended at */10 7-22 * * * (every 10 minutes during business hours, idle at night); the target at */10 * * * * (every 10 minutes all day). The source is paused at night because finance month-end closing often runs overnight, and triggering API calls then could cause exceptions.
4. Go-Live Cadence: Gray-launch with one document type or customer first; once reconciliation is confirmed correct, then open up all-day scheduling.

Lessons Learned

• FBillNo Concatenation Conflicts: Using FBillNo alone as the unique key collides with existing order numbers in the business system—you must concatenate FID. When FID is empty, the concatenated result duplicates. Confirm FID is non-null in the source response.
• Detail Row Omission: executeBillQuery returns master-table fields by default. If detail fields (like FREALRECAMOUNTFOR_D) are not explicitly listed in FieldKeys, the response will have empty values and the entire amount will come through as null. A typical mistake is checking only the master-table fields.
• Approval Time Not Maintained: LAST_SYNC_TIME must be written back after every successful sync, otherwise the next run will either miss records or duplicate them. Qeasy's incremental variables maintain this automatically, but if the source field name changes, it must be updated in sync.
• Master vs. Detail Date Mismatch: The actual posting date on a detail line may differ from the master FDATE. This strategy uniformly uses the master date; the business needs to accept this simplification.
• Constants That Later Need to Change: fbookedType is hardcoded as "银行转账". If acceptance drafts or third-party payments need to be supported later, this must become a variable field. In Qeasy, centralizing such constants into a "constant mapping table" allows one-line changes later without touching every strategy.

Applicable and Non-Applicable Scenarios

Applicable: Finance system is Kingdee Cosmic, business system needs per-collection-detail posting, reconciliation timeliness requirement is high (10-minute level). Not applicable: Scenarios requiring bidirectional sync where receipt bills are written back to Kingdee, scenarios requiring sync of unapproved bills, or scenarios where receipt bills need to be split across multiple order lines by allocation rules (the latter requires script extension and is out of scope for this strategy).