Sync Negative Bills from JikuCloud to Kingdee Refund Vouchers: A Single-Strategy Tutorial

What This Strategy Solves

After an e-commerce business runs for a while, the finance team almost always hits the same problem: refunds appear as "negative bills" in the trading system, but they have to land in Kingdee Cloud as a formal "Refund Payment Voucher," with fields like settlement organization, currency, business date, and voucher type filled correctly per Kingdee's rules. In one real project, we saw a customer who never centralized this mapping end up with mismatched ledgers three months later, and finance had to reconcile everything manually. This strategy's value is simple: one clean document flow that converts negative bills into Kingdee refund payment vouchers so both sides stay in sync.

Data Flow and Field Mapping

The flow is one-way: JikuCloud (source) → Qeasy Data Integration Platform (middleware) → Kingdee Cloud (target). The source uses acs.billinfo.get to query bills in the last 60 days; the target calls batchSave to write refund payment vouchers. Here is a key-field comparison (the full mapping is centrally maintained in Qeasy's "Field Mapping"):

In the middleware, we use Qeasy's "centralized code mapping" pattern to keep the account-name → settlement-org rules in one place. When new accounts are added later, only that one node needs to change — the schedule stays untouched.

How to Configure in Qeasy

In the Qeasy Integration Platform, this strategy is usually built in four steps:

1. Create the source connection. Pick JikuCloud, fill in the app credentials and store scope, choose the acs.billinfo.get API, hard-code pagination pageIndex=0 and pageSize=100, and use the expression from_unixtime((CURRENT_TIME-5184000),'%Y-%m-%d %H:%i:%s') for the start time and the current time for the end time — this gives a rolling 60-day window.
2. Create the target connection. Pick Kingdee Cloud, choose batchSave, fill fixed-value fields such as organization, currency, and voucher type per Kingdee's spec; set FBillNo as the idempotency field.
3. Configure field mapping. In Qeasy's mapping canvas, drag the fields above into place. For FSETTLEORGID, write the CASE WHEN in a script function; for FDATE, use the date-formatting function. Keep all mappings in one independent node so they are easy to audit later.
4. Set up scheduling. The source runs at 33 22 * * * (a 60-day rolling pull at 22:33), and the target runs at 53 5 * * * (write into Kingdee at 05:53 the next day). The buffer between the two keeps them from racing.

Implementation Steps

We typically recommend a three-phase rollout:

• Phase 1: Increment starting point. Run one historical backfill first, pushing all negative bills in the 60 days before go-live into Kingdee to validate the mapping and idempotency. A safe approach is to "Save" (not "Submit") the Kingdee voucher and let finance review in batch before submitting.
• Phase 2: Full-volume trigger. Run the source query and target write on a daily schedule. Run increment and full-volume in parallel: the source uses the time window as the increment boundary, and the target uses FBillNo for idempotent deduplication. Even if the source is re-pulled, no duplicate voucher will be created.
• Phase 3: Schedule frequency. Once a day for the source is enough — the accounting date of an e-commerce bill rarely changes within the same day. The target follows the source. If an emergency refund needs to be backfilled, the source trigger can be switched to a manual run temporarily.

Lessons from the Field

1. Hard-coding the settlement-org mapping in the script. A common mistake is putting CASE WHEN directly in the request body — once you have many accounts, it becomes a mess. The safer approach is to extract the mapping into Qeasy's "Code Mapping Table" and let the script only reference variables.
2. Hard-coding the time window as a fixed date. Many people write bookTimeStart as a fixed 2024-01-01 and end up missing bills the next year. Use a rolling expression like from_unixtime(CURRENT_TIME-5184000) so the window always tracks the current time.
3. Negative amounts get their sign flipped. The source returns negative values, but the target applies an absolute-value conversion by default, so all vouchers land in Kingdee as positive "Receipt Vouchers." In the mapping, explicitly "preserve the source sign," and on the Kingdee side restrict the voucher type to "Refund Payment Voucher."
4. No idempotency key set. If the source re-runs, the target creates duplicates and Kingdee returns "BillNo already exists." Setting FBillNo = billAccountNo essentially fixes it; also turn on idCheck in Qeasy.
5. Save and Submit mixed together. In v1, we had Qeasy submit vouchers directly. One mapping mistake created a pile of wrongly-submitted vouchers. We later switched to "Save" + a daily batch submit by finance, which closes the loop cleanly.

When to Use, When Not to

This strategy fits multi-store, multi-payment-channel e-commerce or new-retail businesses with stable refund volumes, where negative bills must land in Kingdee as formal refund payment vouchers grouped by settlement organization. It does not fit real-time refund scenarios — this is a T+1 schedule, so for minute-level latency requirements, use an event-queue direct push. It is also a poor fit if the source bill schema changes frequently, since mapping maintenance cost will quickly climb.