Date-Range Report to Other Receivable Voucher: A Practical Guide to Cross-System Receivable Fee Synchronization
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:
| Meaning | Source Field | Target Field | Handling Notes |
|---|---|---|---|
| Unique voucher key | id | FBillNo | Composed of {{id}}-{{feeType}}-{{marketName}}-TAX, used as idempotency key |
| Third-party bill no. | id | FHvtThirdSrcBillId | Passed through for back-tracing |
| Fee type | feeType | FHvtThirdCustomNote / line item | Stored in custom note for business identification |
| Time window | purchaseStartDate / purchaseEndDate | Voucher date | Use purchaseStartDate as business date |
| Market / store | marketName | Department / dimension | Maintained via encoding mapping table |
| Source identifier | Fixed value | FHvtThirdSrcType | Write as constant to distinguish data origin |
How to Configure in Qeasy
Key configuration points for this strategy on the Qeasy Data Integration Platform:
- Source API configuration: Use
WebAPI+POST. Pagination paramspage=1,pagesize=100. Time window uses variables{{LAST_SYNC_TIME|date}}and{{CURRENT_TIME|date}}, automatically advancing with the schedule. - Idempotency key design: Enable
idCheck. The voucher number rule is{{id}}-{{feeType}}-{{marketName}}, with-TAXsuffix appended on the target side to avoid collision with other downstream chains. - 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.
- Phased header-then-line processing: Write the header first successfully, then fill in line items. This avoids half-successful vouchers left hanging.
- Target
batchSave: Use theEXECUTE-type interface withbuildModel=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 to30 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
- 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.
- Composite key without suffix.
idis 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. - Market code changes not propagated back. After a store closes or merges, the source
marketNamevalue 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. batchSavewhole-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.- 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
feeTypeas 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.