Sales Settlement Currency Query API Tutorial: Field Mapping to Kingdee Integration

What This API Solves

In multi-currency business scenarios, settlement currency master data is the foundation of monetary fields on sales orders, contracts, and receipts. When a retail enterprise integrates Sales Xiaoshouyi CRM with Kingdee Cloud Galaxy, the trickiest part is not the orders themselves but misaligned currencies—RMB stored as CNY, RMB, or simply empty—causing reconciliation failures across systems. This API pulls settlement currency master data via Sales Xiaoshouyi WebAPI /rest/data/v2/query, serving as the authoritative source for cross-system currency alignment and avoiding endless data fixes downstream.

API Capability Overview

• Authentication: OAuth2 authorization code mode; obtain access_token from the Sales Xiaoshouyi open platform before calling.
• Method & Endpoint: GET /rest/data/v2/query with parameters in the query string.
• Request Parameters: table (object API name, default customEntity70__c), select (comma-separated fields), where (SOQL-style filter), limit (page size, default 10, max 1000), offset (pagination offset).
• Response Structure: Standard { records: [...], totalSize, done }, each record being an object of fields.
• Pagination: Traditional limit + offset; in Qeasy, the adapter automatically calculates pages from totalSize and loops until done=true.
• Incremental Mode: The native API does not expose a lastModifiedTime field, so the industry uses a quasi-incremental approach with full pulls plus a time-window filter.
• Scheduling Recommendation: Typical schedule */30 23 * * * (runs at 23:00 and 23:30 daily), avoiding business peak hours.

Typical Field Mapping

How to Configure on Qeasy

1. Adapter Selection: Choose "Sales Xiaoshouyi WebAPI" as source, set endpoint to /rest/data/v2/query, and Table to customEntity70__c.
2. Field Mapper: In Qeasy's field mapper, map id to the target "Currency Primary Key", customItem8__c to "Currency Code", and name to "Currency Name". Qeasy automatically normalizes null and empty strings.
3. Target Configuration: Set Target to "Write No-Op" since this is a pure query strategy; data lands on the platform for downstream Kingdee currency alignment and document synchronization reuse.
4. Scheduling & Pagination: Qeasy's looper automatically paginates by totalSize; raise single-page limit to 500 to reduce request count.
5. Primary Key Validation: Enable idCheck=true along with autoFillResponse to prevent duplicate writes.

Cross-Solution Practical Points

1. Build cross-reference using Kingdee currency codes as the baseline: Kingdee Cloud Galaxy currency codes are stable master data; align Sales Xiaoshouyi's customItem8__c to them so sales order sync does not break due to naming mismatches.
2. Synchronize currency master data before business documents: Always run the currency strategy first, then trigger downstream chains such as sales orders and receipts; otherwise, "currency not found" exceptions occur.
3. Watch out for duplicate name field definitions: When the source config declares name twice in response, Qeasy uses the last declaration only; preview the actual response on the platform before defining mappings.
4. Infer custom field meanings from the strategy name: Fields like customItem8__c and customItem10__c without business labels must be interpreted by strategy name ("Settlement Currency"); do not reuse mappings from other master data strategies.
5. Use time-window filtering for incrementals, not API fields: The native API does not return lastModifiedTime; a safe approach is adding LastModifiedDate >= LAST_N_DAYS:1 to where and rerunning daily so new currencies enter the system promptly.
6. Schedule away from business peaks: Running at 23:00 and 23:30 is empirical; it avoids daytime write peaks and leaves a retry window before dawn.

Pitfall Recap

• Pitfall 1: Using name as the code. A retail enterprise matched "RMB" directly to Kingdee, but Kingdee stored "CNY", causing all order currency fields to fail. Fix: Use customItem8__c (code) for cross-system mapping; name is for display only.
• Pitfall 2: Treating customEntity70__c as a business field. Mistaking it for a currency code yields parent object references downstream that match nothing. Fix: Open the object in the Sales Xiaoshouyi backend first to inspect actual content.
• Pitfall 3: Leaving limit at the default 10. With many currencies, request count explodes and one run takes over ten minutes. Fix: Raise limit to 500–1000 and let Qeasy's looper finish in one pass.
• Pitfall 4: Misusing full delete-and-insert for incrementals. Assuming a query strategy means overwrite-on-rerun wipes downstream cached codes, breaking in-flight order references. Fix: Use upsert semantics for currency master data—insert and update only, never delete.
• Pitfall 5: Schedule colliding with Kingdee settlement. Running currency sync at 1:00 AM clashes with Kingdee's daily settlement and triggers table locks. Fix: Shift to 23:00 and 23:30 to avoid the Kingdee settlement window.

When to Use

Suitable for bidirectional integration between Kingdee Cloud Galaxy and Sales Xiaoshouyi requiring aligned settlement currency master data; not suitable for lightweight single-point queries on Sales Xiaoshouyi or scenarios with a single currency and no alignment need. Multi-currency, cross-border projects involving order and receipt flows across systems are strongly advised to build this currency query strategy first.