Kingdee Cloud Outbound Application API Field Handbook: Guanyi Supply Chain Integration Tutorial

What This API Solves

Kingdee Cloud's Outbound Application is the source document for downstream operations such as sales shipments and e-commerce fulfillment. In supply chain integration scenarios, retail or e-commerce businesses typically need approved documents from Kingdee to flow into Guanyi to create sales orders. This API uses ExecuteBillQuery with an incremental filter by approval date and the status flag FDocumentStatus='C' (approved only), synchronizing Outbound Applications from Kingdee into Guanyi to enable a B2B-to-B2C downstream flow.

API Capability Overview

• Authentication: User/password login against the Kingdee Cloud private deployment, hitting the WebAPI via POST. The FormId is STK_OutStockApply.
• Request structure: Core parameters are FormId, FilterString, FieldKeys, Limit, StartRow, and TopRowCount. The FilterString follows FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FDocumentStatus='C'.
• Response structure: A Result array is returned. Each record carries base fields (Id, Number, Status) plus business fields; the line item field BillEntry is a nested array.
• Pagination: Use StartRow + Limit (default 2000 per page, adjustable) to iterate the master document set; line items are returned inline.
• Incremental mode: Approval date is the cursor. The schedule runs every 10 minutes from 7 to 23 to capture newly approved or changed documents.

Typical Field Mapping

How to Configure in Qeasy

On the Qeasy Data Integration Platform, this API is typically packaged as a "Kingdee Cloud query adapter":

1. Source adapter: Choose the Kingdee Cloud connector and configure the private address, account set, and user credentials. Sensitive fields are encrypted on the platform side.
2. API template: The platform ships a visual panel for ExecuteBillQuery with the STK_OutStockApply metadata pre-loaded. FieldKeys can be generated by ticking the required fields.
3. Filter conditions: FilterString supports the template variable {{LAST_SYNC_TIME|dateTime}}, and the platform automatically injects the last sync timestamp without manual stitching.
4. Field mapper: The mapper recognizes Kingdee's Id/Name/Number triplets and splits them into separate columns, making one-to-one mapping to Guanyi fields straightforward. Custom fields (F_UQRW_*) are exposed by their raw keys so engineers can define target aliases themselves.
5. Target write: Configure the target as Guanyi sales order creation gy.erp.trade.add. Qeasy automatically validates required fields such as shop_code, details, and receiver_* per Guanyi's constraints.

Cross-Scenario Best Practices

1. Approval date is the most reliable incremental cursor: prefer FApproveDate over FModifyDate to avoid re-pushing the same document after a reject/resubmit cycle.
2. The triplet pattern is Kingdee's universal language: organization, department, customer, and person all expose Id+Name+Number. Cross-system reconciliation almost always uses _Number; _Id is only used for in-Kingdee joins.
3. Always process the full BillEntry array: material codes, requested quantities, inventory org, and line remarks must all be mapped into Guanyi details, otherwise downstream rows will be missing.
4. Custom field naming varies by customer: F_UQRW_* is one customer's prefix; others may use F_Text*, F_YT*, etc. Maintain an "alias table" in metadata management since it's impossible to enumerate them generically.
5. Status linkage must be closed-loop: sync both cancel status (CancelStatus) and close status (FCloseStatus) to the Guanyi side, otherwise a document already canceled in Kingdee may continue to generate push orders and shipments downstream.
6. Multi-org, multi-book requires separate strategies: in the same Kingdee deployment with different books/orgs, configure distinct Source settings and filter conditions to prevent data crosstalk.

Pitfall Retrospectives

• Pitfall 1: Unapproved documents are also pushed. Missing FDocumentStatus='C' in FilterString causes drafts/in-progress documents to be synced to Guanyi; they get pushed again when approved, producing duplicates. Safe approach: always include the C condition in the filter, and add a DocumentStatus assertion in Qeasy's mapper.

• Pitfall 2: Only the first line item is taken. BillEntry is an array; a single Kingdee request can return 100+ paginated lines, and limiting via FilterString row numbers is ignored. Safe approach: either bump Limit to pull everything in one shot, or enable Qeasy's "inline line item pagination" switch.

• Pitfall 3: Custom fields come back empty. Kingdee's custom fields must be explicitly listed in FieldKeys; otherwise the response simply omits the field and the frontend only sees null. Safe approach: add all required custom fields to FieldKeys and declare them in metadata alongside number/id.

• Pitfall 4: Customer code mapping chaos. Using CustId_Number directly as shop_code breaks when one customer corresponds to multiple shops. Safe approach: maintain a customer-code-to-shop-code mapping table inside Qeasy's CASE function, and split orders one-to-many as needed.

• Pitfall 5: Time zone and date format mismatch. Kingdee's approval date is local time, while Guanyi's deal_datetime defaults to UTC, leading to a few hours of drift. Safe approach: explicitly declare the time zone (default +08:00) in the platform transformer instead of relying on the runner's local zone.

When to Use

This pattern fits hybrid retail/e-commerce architectures where Kingdee Cloud acts as the ERP master data and approval gate, and Guanyi Cloud serves as the e-commerce order storefront. The typical scenario is distributing B2B-approved documents into B2C sales orders downstream. Boundary: it only suits incremental sync of approved documents, not draft collaboration or workflow intermediate states. If real-time push is required, switch to webhook/event triggers instead of polling.