Authoritative Tutorial on the Interface Field Manual for Guanyi Cloud & Kingdee Cloud Cosmos Supply Chain Integration

What This Interface Solves

In real e-commerce retail operations, Guanyi Cloud manages front-end transactions and inventory flows while Kingdee Cloud Cosmos handles back-end finance and production planning. Without a bridge between the two, stock ledgers drift, forecasts miss materials, and receipts/payments get duplicated in accounting. The interface set this tutorial focuses on bi-directionally connects 23 document types — purchase orders, delivery orders, return orders, inventory count sheets, expense flows and more — into a stable, observable, replayable, routable integration pipeline.

Interface Capability Overview

Guanyi Cloud / Guanyi Cloud · Qimen exposes documents through APIs in the gy.erp.*.get style (purchase orders, transfer orders, count orders, delivery orders, return orders, expense flows, etc.), pulled incrementally on approve_date / delivery_date / create_date; full snapshots are used for initial deployment or historical backfill. The Kingdee Cloud Cosmos target side writes into PLN_FORECAST, SAL_OUTSTOCK, SAL_RETURNNOTICE, STK_TransferDirect, STK_MISCELLANEOUS, receipt bills, payment bills and similar business objects through its open platform. Authentication uses OAuth-style signing with AppKey / AppSecret + tenant identifier. Request bodies are mainly Form / JSON; responses return a unified result code with a data list. Pagination is controlled via page_no / page_size, with 50–200 per page recommended. Incremental cursors can be persisted into the lightly cloud scheduling context based on "last modified time".

Typical Field Mappings

How to Configure on Lightly Cloud

In the lightly cloud Data Integration platform, both the Guanyi Cloud source adapter and the Kingdee Cloud Cosmos target adapter are pre-built, so calls like gy.erp.*.get and SAL_OUTSTOCK/Save do not require hand-written signing or pagination logic. The field mapper supports five mapping types: DIRECT (pass-through), TRANSFORM (function / date / CASE conversion), COLLECTION (detail-array reference), CONSTANT, and SCRIPT (scripts, e.g., judging FTransferBizType for transfer order types). Routing logic can be configured directly in the strategy's "Filter Condition" via shop + warehouse CASE expressions, or through Groovy / JS scripts to distinguish channels (JD self-operated vs non-JD self-operated). The product-to-lightly-cloud empty-operation strategy essentially pre-loads item categories as the owner-joint-lookup data source, so transfer orders and return orders can query across strategies in the AfterSourceInvoke hook. At the scheduling layer, lightly cloud allows each strategy to set its own Cron and incremental cursor field. On exception handling, single-row failures default to the dead-letter queue with an alert, without blocking subsequent data.

Cross-Solution Practical Points

1. Item master data first: The Guanyi item → lightly cloud empty-operation strategy must run before transfer orders and return orders because it serves as the "category → owner" lookup source.
2. Shop + warehouse combined routing: Delivery orders cannot be routed by shop alone. In real projects, the same shop from different warehouses lands on different target documents (e.g., the Hong Kong warehouse goes to a direct transfer order, others to a sales outbound order).
3. Channel routing must be front-loaded: JD self-operated return orders go to direct transfer orders; non-JD self-operated ones go to sales return orders. The filter condition must be pushed down at the source pull to avoid reverse correction downstream.
4. Pick the incremental field per document type: Use approve_date for purchase orders, delivery_date for delivery orders, and modification time for items. Do not use create_date for all — the miss rate will be too high.
5. Tiered finance scheduling: History and day-to-day expense flows run as two strategies. Currency lookup must run before finance strategies for amount validation.
6. Append owner suffix to document numbers: When the same source document lands on multiple target organizations, append -owner_org to the code to avoid "duplicate document number" errors on the Kingdee side.

Pitfall Retrospective

• Pitfall 1: Owner was not pre-loaded. When transfer orders sync, owner_org cannot be resolved and the default owner is used, misaligning the inventory org. The safe move is to run the item empty-operation strategy for 1–2 cycles first, confirm the category→owner mapping table has data, then enable business documents.
• Pitfall 2: Shop + warehouse mapping was written as single-condition CASE. Only shop_code → FSaleOrgId was configured, so different warehouses under the same shop were wrongly merged. Use multi-condition CASE expressions or scripts.
• Pitfall 3: Missing positions were not completed. For JD self-operated return orders routed to transfer orders, the receiving warehouse has position gaps that were not patched, causing Kingdee errors. Add a TRANSFORM fallback after the COLLECTION mapping.
• Pitfall 4: create_date was used as the incremental cursor. Newly created but unapproved documents were skipped, then approved the next day, breaking the downstream accounting period. Switch to approve_date or delivery_date.
• Pitfall 5: Accessory SKUs leaked into sales outbound details. Accessories in delivery-order details were synced along, polluting sales outbound totals. Add an accessory SKU filter inside AfterSourceInvoke.

When to Use

This interface set fits e-commerce retail enterprises (multi-shop, multi-warehouse, multi-owner) that need to bridge Guanyi Cloud and Kingdee Cloud Cosmos for supply chain integration. Typical scenarios: internal purchase → forecast planning, sales outbound and return orders routed by channel, inventory count profit/loss automatically generating miscellaneous in/out orders, expense flows and sales receipts/payments flowing into the general ledger. It is not recommended for pure manufacturing, pure wholesale distribution scenarios, or for organizations that lack mature master-data governance.