From Jushuitan Inventory Loss to KIS Private Cloud Other-Outbound: A Practical Breakdown of One Inventory Sync Strategy
What This Strategy Solves
Inventory loss happens almost daily in a retail warehouse: breakage, expiry, loss, write-off. Loss documents recorded in Jushuitan need to flow into KIS Private Cloud as "other-outbound" documents, hitting the cost ledger. The chain looks like mere document transport, but it actually controls inventory accuracy and the month-end closing rhythm. Once the two sides drift apart, finance spends a lot of time explaining the variance.
Data Flow and Field Mapping
Data starts from Jushuitan, enters the Qeasy integration platform's middle layer, where encoding mapping, field enrichment, and header/body splitting happen, then is written into KIS Private Cloud.
| Business Meaning | Jushuitan (Source) | Middle Mapping | KIS Private Cloud (Target) |
|---|---|---|---|
| Document type | Loss doc (configurable type code) | Type whitelist filter | Other-outbound doc |
| Document number | Platform doc number | Idempotency key | KIS doc number |
| Document date | business_time | Pass-through | Business date |
| Warehouse | Warehouse code | Warehouse mapping table | KIS warehouse code |
| Product code | SKU code | Product mapping table | KIS material code |
| Quantity | Loss quantity | Sign normalization (loss → positive) | Actual outbound qty |
| Remarks | Remarks field | Append source identifier | KIS remarks |
Centralized encoding mapping is a common pattern among Qeasy customers: once the mapping between Jushuitan SKUs and KIS material codes is scattered across multiple scripts, maintenance becomes a disaster later. Unifying it in a mapping table is what holds up under change.
How to Configure in Qeasy
- Data source access: Jushuitan via its open platform, KIS Private Cloud via its private interface. Create source and target data source connections in Qeasy, configuring quotas, rate limits, and timeouts in one go.
- Pull strategy: For loss documents, use "incremental by modification time + document type whitelist" so transfer and write-off documents don't get pulled in by mistake.
- Middle layer processing: Header/body staged processing is another common pattern—land the header first, then handle the body; on any line failure, roll back the whole document or mark it for manual review to prevent "half documents."
- Encoding mapping: Product codes, warehouse codes, customer/department codes are centrally maintained in the mapping center; field enrichment (e.g., default cost center) is also done here.
- Push to KIS: Assemble payloads per the KIS header → body interface spec; KIS has strict requirements on doc date, unit price, and batch number, so format and precision validation must run before the push.
- Write-back and reconciliation: Write KIS-returned doc numbers and audit status back to the Qeasy log, forming a two-way audit trail.
Implementation Steps
We usually roll this strategy out in three phases:
- Phase 1: Incremental starting point. Run "incremental by modification time" for a week to validate mapping, rate limits, and KIS write success rate. At the same time, build an idempotency table of Jushuitan doc number ↔ KIS doc number to avoid duplicate documents on reruns.
- Phase 2: Full-volume trigger. On the go-live day, do a one-time backfill of historical data; all loss history flows in at once. Running full and incremental in parallel is a common Qeasy practice—full for migration, incremental for daily use.
- Phase 3: Steady-state scheduling. Move to near-real-time scheduling, usually every 5–15 minutes. Failed documents go to a retry queue with alerts, and escalate to manual handling past a threshold.
Keep the order straight: first incremental to stabilize mapping, then full-volume as a safety net, finally high-frequency scheduling. Reverse the order and early troubleshooting gets buried under historical data.
Pitfall Retrospective
- Type whitelist misconfigured. Jushuitan's "loss" and "write-off" document fields look similar; without a whitelist, write-off documents also get pushed as losses, and the cost account on the KIS side ends up wrong.
- Quantity sign handling reversed. Loss quantities may be negative or positive at the source depending on convention; pushing to KIS without converting makes inventory drift further and further. A safe approach is to do an explicit sign normalization in the middle layer.
- KIS doc date format not normalized. KIS has strict requirements on date, unit price, and batch number format; if the source is a raw string and gets pushed directly, the API rejects it. Adding format and precision validation in Qeasy is recommended.
- Header succeeded but body failed. A classic mistake: the header landed first, the body failure was ignored, and KIS ends up with "an other-outbound doc with no lines." Header/body staging with rollback or marking on failure is mandatory.
- Idempotency key not designed. The platform doc number alone is sufficient as an idempotency key, but at customer sites people often stuff it into the body as a remark, causing reruns to land duplicates. The idempotency key should be a separate field with independent validation.
Applicable and Non-Applicable Scenarios
Applicable: Small-to-mid retail and trading enterprises where Jushuitan acts as the main retail/e-commerce warehouse and KIS Private Cloud as the financial and inventory accounting system; internal business documents like loss and write-off that need to be settled daily. Not applicable: Multi-warehouse, multi-organization manufacturing scenarios that require line-by-line audit and strict batch/serial validation; or compliance-strict scenarios where loss documents must be manually journaled in KIS rather than auto-generated by the system.