Practical Guide: Syncing "Other Cash Funds Receipt" from JiKeYun to Kingdee Cloud Cosmos
What This Strategy Solves
In projects integrating supply chain with finance, a common pattern is: the upstream business system (here, we use JiKeYun as an example) handles orders, receipts, and bookkeeping, while the downstream finance system (Kingdee Cloud Cosmos) handles final posting and voucher generation. Both systems need to keep the same "Other Cash Funds Receipt." It looks like just pushing one document, but in practice it involves unifying currency, organization, document type, and status fields. If any mapping is off, month-end reconciliation will break. This article addresses exactly that — pushing business documents into the finance domain.
Data Flow and Field Mapping
The pipeline is one-way: JiKeYun → Qeasy Integration Platform → Kingdee Cloud Cosmos.
Key field mapping (only fields that typically cause trouble):
| Business Meaning | Source (JiKeYun) | Middle Layer (Qeasy Mapping) | Target (Kingdee Cloud Cosmos) |
|---|---|---|---|
| Document Number | Business document number | Pass through | FBillNo |
| Document Status | Approved flag | Convert to code | FDOCUMENTSTATUS (Z=Draft / A=Created) |
| Document Type | "Other Cash Funds Receipt" | Dictionary mapping | FBillTypeID (SKDLX98_SYS) |
| Currency | CNY / USD etc. | Centralized code table | FCURRENCYID (e.g., PRE001) |
| Business Date | Created timestamp | Normalized to date | FDATE |
| Settlement Org | Business org code | Org mapping table | FSETTLEORGID |
Currency, organization, and document type codes should always live in Qeasy's centralized mapping table, never scattered inside a single strategy.
How to Configure in Qeasy
Inside the Qeasy integration platform, this strategy is a typical "query + execute" pattern: source uses QueryStrategyData (POST, QUERY), target uses batchSave (POST, EXECUTE).
Key configuration points:
- Strategy ID and status filter: The source request must include
strategy_idandstatus. Use0(pending) to pick up unprocessed records and avoid re-fetching completed ones. - Time window: Use
created_at_beginandcreated_at_endto define the incremental window.beginshould be the last successful run time,enduses the{{CURRENT_TIME}}template variable. - Hardcoded document type: This strategy is fixed to "Other Cash Funds Receipt", mapped to
SKDLX98_SYSon the Kingdee side. Don't auto-detect — hardcode it for stability. - Default currency: In domestic retail/manufacturing scenarios, default to
PRE001. For multi-currency businesses, build separate strategies. - Auto-fill response: Enable
autoFillResponseon the source side, setbuildModel=falseon the target side so Qeasy constructs the request body from target metadata — less hand-written JSON. - Idempotency: Enable
idCheck=trueon the target side, deduplicate by FBillNo to avoid duplicate vouchers on retries.
Implementation Steps
After a few real deployments, we usually split the rollout into three phases:
Phase 1: Confirm the incremental starting point
At first go-live, fix created_at_begin to the 10-digit Unix timestamp of 00:00:00 on the launch date, and use {{CURRENT_TIME}} for created_at_end. Run a dry execution first to confirm the source can stably fetch data and the target can accept it.
Phase 2: Backfill (optional) If a large volume of historical documents needs to be backfilled, use Qeasy's "full trigger" to extend the window to the past 90 days in one go. Once it finishes, immediately switch scheduling back to incremental mode to avoid re-fetching history daily.
Phase 3: Scheduling frequency
We suggest the source run hourly, and the target run during off-peak hours (e.g., 23 2 * * *) to avoid the finance closing window. The two sides don't need the same frequency; what matters is that the incremental time windows connect continuously.
Lessons Learned
- Missing currency code: In one deployment, USD documents were pushed as CNY, causing currency mismatch and wrong exchange rates on the Kingdee side. The safe approach is to maintain currency fields in Qeasy's central mapping, requiring every new currency to be registered first.
- Auto-detecting document type: Don't let the strategy auto-judge which kind of receipt it is. When business users rename a field in the source, debugging becomes painful. Hardcoding
SKDLX98_SYSis far more reliable. - Passing status as a raw string: The source sends the Chinese word "已审核" (Approved); the target expects a code. Without conversion, it errors out. Header and line status fields should be configured in separate stages — don't mix them.
- Misaligned incremental starting point: Forgetting to record the first successful run time caused yesterday's data to be re-fetched the next day, producing duplicates. The safe approach is to use Qeasy's cursor recording feature to automatically save
last_success_time. - Oversized target batches: Kingdee's
batchSaverejects overly large batches on the server side. Keep each batch under 200 records and retry failed batches separately.
When to Use and When Not to
Use when: The upstream business system and downstream finance system are separated, and business receipt documents need to be pushed into the finance domain for voucher generation by a fixed document type — especially when document type, currency, and organization are already standardized.
Don't use when: Cross-entity, multi-currency scenarios requiring automatic FX conversion (build a dedicated FX strategy instead); or scenarios where the source documents are frequently voided and the void status must sync back to the target — this strategy does not cover reverse status sync.