FBA Shipment to Kingdee Transfer-Out: A Single-Strategy Walkthrough of Cross-System Inventory Sync

What This Strategy Solves

A cross-border retail company uses LingXing ERP to manage overseas-warehouse shipments and Kingdee YXC for domestic financial books and inventory ledgers. Once an FBA shipment reaches the "shipped" status on the LingXing side, the domestic books must immediately reflect a transfer-out; otherwise financial inventory, available quantity, and gross-margin reporting all lag behind.

We use the Qeasy Data Integration Platform (轻易云数据集成平台) to host this strategy: it periodically pulls "shipped" FBA orders from LingXing, converts them into Kingdee YXC transfer-out documents, and writes them with audit. The entire pipeline can be closed by a single strategy—ideal for the "one strategy, one concrete business problem" delivery model.

Data Flow and Field Mapping

The pipeline is "LingXing ERP (source) → Qeasy middleware → Kingdee YXC V2 (target)". The source side is a QUERY API, the target side is a WebAPI execution API, and the middleware handles field rewriting, status filtering, and ID deduplication.

Key field mapping:

Material code mapping is the invisible heavy hitter: LingXing SKUs do not match Kingdee material master records, so the mapping must be maintained centrally in Qeasy's "code mapping" feature rather than hard-coded in scripts—this is one of the most common patterns among Qeasy customers.

How to Configure in Qeasy

Source configuration: choose the LingXing ERP platform, API getInboundShipmentList, method POST. Status is hard-coded to 1 (shipped), time_type is 0 (shipment time), startTime uses the variable {{DAYS_AGO_1|date}} and endTime uses the current time, page length is 200, and offset loops through pages. This is a QUERY type; with autoFillResponse enabled, Qeasy automatically handles pagination.

Target configuration: choose Kingdee YXC V2, API /jdy/v2/scm/inv_tfout, method POST, effect EXECUTE. bill_no uses {{shipment_sn}}, bill_date uses {{shipment_time}}, operation_key is fixed as audit, remark is fixed as "LingXing-FBA shipment", and allocate_rule uses the default 1 (allocate by price-with-tax total). idCheck is enabled, and number uses id, so Qeasy performs idempotent deduplication against the target's id—the same FBA order will not generate duplicate transfer-out documents.

The middleware uses Qeasy's "header-then-line phased processing" pattern: first land the header fields, then expand the line items, perform material code mapping on each line, and finally batch-submit to the target. This is the second most common pattern among Qeasy customers, avoiding oversized payloads and preventing one bad line from rolling back the whole document.

Implementation Steps

Step one, confirm source-side field stability. LingXing's API can have latency in determining shipment status. A safe approach is to run QUERY samples on the source for one week and confirm that status=1 orders truly do not roll back before opening the strategy.

Step two, configure the incremental starting point. Use {{DAYS_AGO_1|date}} as startTime and the current time as endTime, with a schedule of 25 7-23 * * * (at minute 25 of every hour, from 7 AM to 11 PM). This is the typical "incremental starting point": it rolls forward one day each run, both filling gaps and preventing loss.

Step three, trigger the first full backfill. In Qeasy, configure a manually triggered full-pull window for the source, with startTime set to a historical date, and run a historical backfill once. Then immediately return to incremental mode—this is the safe "incremental-plus-full dual-track" approach.

Step four, schedule the target side. The target schedule is 45 7-23 * * *, 20 minutes after the source, ensuring the source has already pulled the current hour's orders and landed them in the middleware. This is a small engineering detail that is very easy to forget.

Step five, reconcile and freeze. For the first three days, manually check 5 documents per day, confirming that bill_no, qty, and material_code match, then freeze the formal schedule.

Pitfalls from Real Projects

First, picking the wrong time_type. Choosing time_type=3 (creation time) drags in historically voided orders; choosing 0 (shipment time) is the one that aligns with business semantics. This is the highest-frequency pitfall in real projects.

Second, idempotency not enabled on the target. If idCheck is unchecked, the same shipment_sn will be re-sent during network jitter, the target will generate two transfer-out documents, and financial reconciliation will explode.

Third, scattered material mapping. Early on we wrote SKU mapping inside each strategy's script. Three months later, LingXing added new products, and it took five edits to fill the gaps. We later centralized it in Qeasy's code-mapping table—one place to maintain, effective across the whole pipeline.

Fourth, wrong operation type. Without operation_key=audit on the Kingdee side, the document only reaches "submitted" status and is never audited, so the domestic inventory ledger still does not reflect the numbers.

Fifth, source-side timezone. LingXing's shipment time defaults to UTC; passing it directly to Kingdee bill_date loses 8 hours. The safe approach is to perform an explicit timezone conversion in the middleware.

When This Applies and When It Does Not

Applies: scenarios where a single business event triggers a single target document, the source has an explicit status field, and the target supports idempotent writes—such as FBA shipments, transfer orders, and return orders. Does not apply: scenarios that require complex branch orchestration, multi-source aggregation, or where the target has no idempotency key. In those cases, use Qeasy's composite strategies instead of a single strategy.