Qeasy Cloud
Get Started

Date-Range Report to Other Receivable Voucher: A Practical Guide to Cross-System Receivable Fee Synchronization

· 何海波· Integration Solutions· 29 views· 4 min read

What This Strategy Solves

The core pain point of cross-system receivable fee synchronization is that the source side exposes a "date-range report" while the target side requires "per-voucher" Other Receivable entries. In one real project, a retail enterprise had to process hundreds of platform fee allocations daily. The source could only be queried by time window, yet the target demanded per-voucher posting with line-level accounting. We used the Qeasy Data Integration Platform to bridge this gap. The core idea is to transform the source's "time window + composite key" into the target's "header + line items," so the two sides reconcile cleanly.

Data Flow and Field Mapping

Data flow: Source system (date-range report API) → Qeasy middleware (aggregation, code mapping, idempotency control) → Target system (Other Receivable voucher save API).

Key field mapping:

MeaningSource FieldTarget FieldHandling Notes
Unique voucher keyidFBillNoComposed of {{id}}-{{feeType}}-{{marketName}}-TAX, used as idempotency key
Third-party bill no.idFHvtThirdSrcBillIdPassed through for back-tracing
Fee typefeeTypeFHvtThirdCustomNote / line itemStored in custom note for business identification
Time windowpurchaseStartDate / purchaseEndDateVoucher dateUse purchaseStartDate as business date
Market / storemarketNameDepartment / dimensionMaintained via encoding mapping table
Source identifierFixed valueFHvtThirdSrcTypeWrite as constant to distinguish data origin

How to Configure in Qeasy

Key configuration points for this strategy on the Qeasy Data Integration Platform:

  1. Source API configuration: Use WebAPI + POST. Pagination params page=1, pagesize=100. Time window uses variables {{LAST_SYNC_TIME|date}} and {{CURRENT_TIME|date}}, automatically advancing with the schedule.
  2. Idempotency key design: Enable idCheck. The voucher number rule is {{id}}-{{feeType}}-{{marketName}}, with -TAX suffix appended on the target side to avoid collision with other downstream chains.
  3. Centralized code mapping: "Market/store" is a typically volatile field. A common pattern among Qeasy customers is to maintain the mapping table in Qeasy's "Code Mapping" node centrally, rather than scattered across scripts. New markets only require adding one row.
  4. Phased header-then-line processing: Write the header first successfully, then fill in line items. This avoids half-successful vouchers left hanging.
  5. Target batchSave: Use the EXECUTE-type interface with buildModel=false. We control the JSON assembly, and the target system only handles persistence.

Implementation Steps

Phased scheduling is the key to keeping this strategy stable:

  • Phase 1 · Incremental baseline: Run a full sync first with a time window of "from launch to now" as the baseline.
  • Phase 2 · Incremental rolling: Source schedule set to 15 20-23,0-9 * * * (every 15 minutes, covering cross-day periods). Target schedule set to 30 2 * * *, posting daily at 2:30 AM.
  • Phase 3 · Dual-track verification: Once the incremental track is stable, retain the full-sync channel as a fallback. Reconcile monthly. This "incremental + full dual-track" pattern is common among Qeasy customers.
  • Phase 4 · Exception monitoring: Failed vouchers enter the retry queue. Alerts trigger when consecutive failures exceed a threshold.

Lessons Learned from the Field

  1. Cross-day time windows cause data loss. When the source queries by "market time" and the schedule triggers at 23:50, the window may span two days, causing part of the data to be re-fetched in the next window. A safe approach is to add a 5-minute overlap buffer and deduplicate via the idempotency key.
  2. Composite key without suffix. id is shared across multiple business lines. Using it directly as the voucher number will collide with the procurement chain. This is where things break. A business suffix (e.g., -TAX) is mandatory.
  3. Market code changes not propagated back. After a store closes or merges, the source marketName value changes, but the target gets stuck on the historical code. The recommended approach is to make the mapping table auditable with version history for every change.
  4. batchSave whole-batch failures don't pinpoint rows. When the target fails the entire batch, troubleshooting is difficult. A safe approach is to perform row-level validation in Qeasy first, then isolate and retry suspicious rows in separate batches.
  5. Tax rate and fee item misalignment. Other Receivable vouchers are sensitive to fee classification. "Platform commission" and "advertising fees" use different accounts. Mixing them up disrupts accounting. A typical mistake is stuffing feeType as a plain string; it should be explicitly mapped to an account in the mapping node.

Suitable and Unsuitable Scenarios

Suitable: Source provides receivable/fee data aggregated by time window, target requires per-voucher posting, and both sides have clear idempotency keys. Unsuitable: Source is event-stream-based (no time-window concept), target does not support idempotency-key deduplication, or fee items require manual judgment and cannot be auto-mapped.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/solutions/strat-erp-kingdee-cloud-1306-tax-0369691a

Comments