Authoritative Tutorial on the Field Handbook for Kingdee Cloud Galaxy Sales Order and Xiaoshouyi Master Data Query APIs

What Problem Does This API Solve

In private-deployment scenarios where Kingdee Cloud Galaxy and Xiaoshouyi coexist, the most common question from the business side is: "For the same order, currency, or bank account, which system is the source of truth?" We encapsulate three high-frequency query interfaces — the Kingdee Sales Order, the Xiaoshouyi settlement currency, and the Xiaoshouyi internal bank account — into QUERY_ONLY strategies that land in the data hub. Downstream code mapping, document synchronization, and receivable reconciliation then consume a single source of truth, avoiding dirty data and uncontrolled call frequency that come from direct cross-system calls.

API Capability Overview

• Authentication: Kingdee Cloud Galaxy uses username/password with data-center authorization in private deployment, and the app must be bound to a specific organization/books set. Xiaoshouyi uses OAuth 2.0 or a session token; private domains need an internal whitelist.
• Request structure: Kingdee uses QueryBill/ExecuteBillQuery style form requests, requiring explicit FieldKeys declaration. Xiaoshouyi uses REST + SOQL style with where/limit/offset.
• Response structure: Kingdee returns nested object arrays; associated fields like FCustId.FNumber require dot-path nested extraction. Xiaoshouyi returns flat JSON with custom objects prefixed customEntity__c / customItem__c.
• Pagination: Kingdee uses Limit + StartRow (typically 100–500 rows per page); Xiaoshouyi uses limit + offset (single-call cap depends on the vendor doc).
• Incremental mode: Kingdee recommends FApproveDate>='{{LAST_SYNC_TIME}}' and FDocumentStatus='C' to pull only approved documents; Xiaoshouyi uses LastModifiedDate >= {{LAST_SYNC_TIME}}.

Typical Field Mapping

How to Configure on Qeasy

In the Qeasy Data Integration Platform, these query strategies are typically implemented through a combination of adapter and field mapper:

1. Adapter layer: Use the official Kingdee adapter, configuring private domain, books set, user, and password in the connection. For Xiaoshouyi, use the custom-object adapter and register customEntity70__c / customEntity36__c as recognized "document types".
2. Scheduling and strategy: The three QUERY_ONLY strategies are orchestrated in parallel in Qeasy's strategy center. Place the master data (currency, bank account) strategies before the sales order strategy so the mapping table is ready when downstream runs.
3. Field mapper: Qeasy's field mapper automatically flattens nested fields like FCustId.FNumber and lets you reference the mapping table directly in mapping expressions to perform FNumber → Xiaoshouyi id conversion.
4. Incremental and retry: The platform provides built-in LAST_SYNC_TIME variables, exponential backoff, and failure tables. The cursor is not advanced unless the batch is committed, which makes break-point recovery straightforward.

Cross-Scenario Practice Points

1. Master data first: Low-frequency entities like currency and bank account must land in the hub before or in parallel with the sales order; otherwise downstream order sync fails on missing mappings.
2. Approved only: Always add FDocumentStatus='C' to the Kingdee incremental condition or the same drafts will be pulled repeatedly, bloating the hub.
3. Declare nested fields: Dot-path fields such as FCustId.FNumber must be fully listed in FieldKeys or the response will silently omit them, often mistaken for an interface error.
4. Mapping tables are the lifeline: Customer, material, currency, and bank account mapping tables are all mandatory; in Qeasy we usually model them as independent master-data strategies referenced by downstream order/contract strategies.
5. Layered scheduling: Order queries every 5–10 minutes; master data daily or every 6 hours. Blind high-frequency scheduling overloads the source and wastes quota.
6. Privacy masking upfront: Contact, phone, and address must be masked or field-level encrypted before landing; otherwise audits and cross-tenant reuse will become a minefield.

Pitfall Recap

• FieldKeys missing nested fields: Kingdee adapter returns {} in 90% of cases because nested fields like FCustId.FNumber were not fully declared. The safe approach is to list every drill-down field up front.
• LAST_SYNC_TIME advanced too early: The cursor was advanced before the full batch landed, leaving some orders lost without a replay clue. We now insist on advancing LAST_SYNC_TIME only after the entire batch succeeds.
• Currency code mismatch: Direct sync without a customItem8__c ↔ FSettleCurrId.FNumber mapping leads to mixed CNY/RMB in orders. The safe approach is to run a full mapping reconciliation script in the hub first, alert on differences, and then go incremental.
• Rate limiting silently dropped: Kingdee private deployment occasionally returns 429; fixed-interval retries that ignore Retry-After will trigger further throttling. Respect the server-side backoff signal.
• Detail rows without foreign keys: Detail rows landed without header FID cannot be joined back to the header. Always return FSaleOrderEntry_FEntryId together with FID in detail mapping.

When to Use

This aggregated QUERY_ONLY pattern is suitable for private environments where Kingdee Cloud Galaxy and Xiaoshouyi coexist and you need to centralize orders and master data into a hub for code mapping and downstream distribution. If the business has already migrated to a single system, or if real-time requirements push you toward event streaming rather than scheduled polling, this pattern is no longer the best fit.