Reverse Sync of Guanyi Expense Flow to Kingdee Payment Refund Voucher: Historical Data Backfill in Practice

What This Strategy Solves

In many customer engagements we see a recurring pain point: the e-commerce backend already records expense flows on a monthly basis, but the finance-side Kingdee Cloud is still relying on manual entry. By month-end, the numbers on the two sides drift apart, accounts are misaligned, and payments and refunds get tangled.

This strategy focuses on a single task: pull already-audited historical expense flows from Guanyi Cloud on a monthly basis, and reverse-generate payment refund vouchers in Kingdee Cloud, so that finance month-end closing has a reliable paper trail.

Its value is not in real-time synchronization, but in historical data backfill — closing the gap for the past several months in one pass, eliminating duplicate manual entry, and keeping both sides consistent.

Data Flow and Field Mapping

The flow is unidirectional: Guanyi Cloud → Qeasy Integration Platform → Kingdee Cloud. The middleware layer handles filtering, pagination, field restructuring, and code translation.

Key field mapping (excerpted from real project configuration, desensitized):

The source interface is gy.erp.finance.billFlowList.get; the target is Kingdee's batchSave.

Configuring on Qeasy

We use the Qeasy data integration platform to host this strategy. Configuration is split into three parts:

Source (Guanyi Cloud)

• Interface: gy.erp.finance.billFlowList.get, POST method;
• Time range dynamically computed via _function for the previous month's first day 00:00:00 to last day 23:59:59, avoiding manual date changes;
• Audit status fixed at 2, fetching only audited records;
• Page size set to 150 — fast enough to finish a month within the window, slow enough to avoid rate limiting.

Target (Kingdee Cloud)

• Interface: batchSave, POST method;
• Voucher type fixed as FKTKDLX02_SYS;
• Currency defaults to PRE001;
• Voucher number, organization, business date are injected via variables from the source records.

Middleware (Qeasy Platform)

• Centralized code mapping: stores, organizations, accounts — fields prone to mismatches — are managed in a dedicated mapping table. When the source changes, the main flow stays untouched;
• Failure retry enabled; a single record failure does not abort the whole batch;
• Idempotency controlled via the source code field, preventing duplicate backfill.

Implementation Steps

This is a "historical data" scenario, so the scheduling logic differs fundamentally from real-time sync. We recommend three phases:

Phase 1: Define the backfill starting point

Confirm with finance which months to backfill. A common approach is to start from the most recently closed month and work backwards — for example, backfilling January through June 2024.

Phase 2: Trigger in batches

Do not run all six months in one shot. We recommend one month per batch; after each month completes, reconcile with finance, and only proceed to the next month once numbers match.

For the cron configuration, setting crontab to 1 1 1 1 1 (all ones) effectively means "manual one-time trigger." In our customer engagements, the usual flow is: manually trigger January 1 via Qeasy, validate the data, then trigger the remaining months one by one.

Phase 3: Reconciliation and archiving

After each batch, spot-check 5–10 vouchers in Kingdee Cloud, focusing on:

• Whether voucher numbers are duplicated;
• Whether business dates fall within the corresponding month;
• Whether settlement organization mapping is correct;
• Whether the amount direction (payment vs refund) matches the source.

Only proceed to the next batch after reconciliation passes.

Lessons Learned

Pitfall 1: Hard-coded time ranges cause data loss

A typical mistake: writing recordedTimeBegin and recordedTimeEnd as fixed dates. After running for three months, the data crossing the month boundary gets missed. The safer approach is to use _function for dynamic computation, for example DATE_FORMAT(DATE_SUB(DATE_SUB(CURDATE(), INTERVAL DAY(CURDATE()) - 1 DAY), INTERVAL 1 MONTH),'%Y-%m-%d 00:00:00'), so the platform auto-computes each month's range.

Pitfall 2: Missing audit-status filter pulls in drafts

If auditStatus is left empty or set incorrectly, the source returns drafts, voided records, and audited records together — and Kingdee ends up with a pile of unintended payment vouchers. Always lock the source to auditStatus=2.

Pitfall 3: Wrong voucher type generates the wrong document

Kingdee Cloud's FBillTypeID has multiple payment voucher types: FKTKDLX01_SYS is a standard payment voucher, while FKTKDLX02_SYS is the payment refund voucher. Pick the wrong one, and the voucher saves successfully but subsequent verification breaks. We encountered this at one retail client — two months of data had to be re-run after discovery.

Pitfall 4: Page size too large triggers rate limiting

Setting pageSize to 500 or 1000 is a common mistake. The Guanyi interface has rate limits; an aggressive page size triggers throttling and returns empty data. A safe range is 100–150.

Pitfall 5: No idempotency control leads to duplicate backfill

If network jitter causes the same batch to be processed twice without idempotency, duplicate vouchers appear in Kingdee. Always use the source code field as the dedup key — the "Idempotency Key" setting in Qeasy exists for this.

When This Applies — and When It Doesn't

Applies: scenarios where e-commerce backend and finance ERP are separated and historical expense flows need one-time backfill; monthly batch archiving of the previous month; month-end reconciliation gap-closing.

Does not apply: real-time sync of payment refund flows (configure a separate real-time strategy); mixing unaudited source data into the batch; scenarios requiring complex verification logic (this strategy only generates vouchers, it does not handle verification status linkage).