Jushuitan Refund Orders to KIS Red-Letter Sales Outbound: A Single-Strategy Sync Tutorial

What This Strategy Solves

In a refund scenario, refund orders from the e-commerce side need to land in the ERP as red-letter sales outbound documents so that revenue and inventory can be reversed. The source lives in Jushuitan, the target in KIS Cloud, and the two document models differ quite a bit: Jushuitan refund orders follow the online refund workflow, while KIS red-letter sales outbound documents must comply with financial accounting rules. The value of this strategy is turning refund events into ERP-side red-letter documents that can be booked and reversed, keeping books and reality aligned.

Data Flow and Field Mapping

Data flow: Jushuitan (refund order) → Qeasy Data Integration Platform (middleware for cleansing, mapping, transformation) → KIS Cloud (red-letter sales outbound document).

Key field mapping table:

The header determines the whole red-letter document; once header info is stable, the body just writes quantity, price, and warehouse line by line.

How to Configure in Qeasy

Create a new strategy in the Qeasy Data Integration Platform. Pick Jushuitan (pull refund orders through its open API) as the source and the KIS Cloud red-letter sales outbound interface as the target. Key configuration points:

First, centralize code mappings. Customer codes, material codes, and warehouse codes should be maintained in a single mapping table, not scattered across transformation scripts. In one real project, we saw hard-coded mappings inside scripts; three months later the business team changed the SKU prefix and the engineer had to update scripts line by line—very costly.

Second, flip signs in the middleware. The source uses positive numbers (refund quantity, refund amount), but the target needs negatives. The safe approach is an explicit conversion function for signs, rather than relying on the target system to flip automatically.

Third, idempotency and deduplication. Refund orders will be queried multiple times; use the source document number as the dedup key. Run records in Qeasy show whether a record was inserted twice.

Fourth, failure retry and alerting. Qeasy retries on network jitter or KIS interface timeouts. The critical part is pushing alerts to the operations group, so red-letter documents do not pile up unnoticed until the next day.

Implementation Steps

A phased rollout is safer.

Step 1: incremental starting point. First confirm the timestamp for Jushuitan refund orders. Start from a low-traffic business moment (for example, early morning) to avoid both missing and duplicate orders. After setting the incremental start time in Qeasy, run a batch of sample data to KIS and check whether the red-letter documents are generated correctly.

Step 2: full backfill trigger. If the business needs historical refund orders, use Qeasy's batch backfill feature for one full run. Switch back to incremental mode immediately after to avoid duplicate pulls.

Step 3: scheduling frequency. Refund events occur much less frequently than shipments, so pulling Jushuitan refund changes every 15 to 30 minutes is reasonable. The exact frequency depends on the customer's order volume—shorten the interval for large volumes and lengthen it for small ones to ease API pressure.

Step 4: canary and reconciliation. During early days, do a daily reconciliation in the morning: Jushuitan refund order count versus KIS red-letter sales outbound count. Investigate any discrepancy the same day.

Pitfalls and Lessons Learned

First, document number write-back timing. Using the Jushuitan refund ID directly as the KIS red-letter document number seems convenient but easily conflicts with existing KIS document numbers. The safe approach is writing the source ID into KIS's external document number field and letting KIS generate its own internal number.

Second, sign reversal mistakes. This is a typical error—pushing refund quantity as a positive number to KIS results in an ordinary blue outbound document, the direction completely reversed. The middleware must handle signs explicitly, and unit tests should assert that amounts and quantities are negative.

Third, missing warehouse mapping. The warehouse the refund actually enters may be a temporary or virtual warehouse, while KIS red-letter outbound uses logical warehouses. Missing mapping causes red-letter documents to stall at the approval step.

Fourth, dependency misconfiguration. If a SKU in a refund order does not exist in KIS material master data, the red-letter document will be rejected. This strategy must therefore declare its dependency: wait for "material master data sync" to complete first. Configure the upstream strategy ID in Qeasy dependencies.

Fifth, weak idempotency keys. Using only the document number as the idempotency key is sometimes insufficient—if a single refund order incurs multiple partial refunds, multiple red-letter documents may result. Use a composite key of "source document number + line number."

Suitable and Unsuitable Scenarios

Suitable: e-commerce retail businesses with stable refund frequency, relatively fixed SKUs, and a need to reverse ERP revenue and inventory immediately. Unsuitable: pure offline retail refunds (which do not flow through Jushuitan), stages where SKUs are highly volatile and material master data is not yet stable, and businesses requiring manual review and signature on red-letter documents.