Kingdee Cloud Galaxy Flagship Edition - Sales Order Query API Field Handbook Tutorial
What This API Solves
The Sales Order Query API (/kapi/v2/dsg5/sm/sm_salorder/queryadd) is used to paginate and pull sales order master data from Kingdee Cloud Galaxy Flagship Edition. In retail and trading scenarios, this is the starting point for syncing ERP documents into CRM or data middleware — without it, downstream customer reconciliation, fulfillment tracking, and cross-system number mapping have no foundation. A typical scenario is pulling Kingdee sales orders back into a CRM for document mapping, or sinking them into a data warehouse for fulfillment analytics.
API Capability Overview
- Authentication: Kingdee Cloud Galaxy OpenAPI auth, requiring an access token in the request header (obtained uniformly by the platform).
- Method: POST, Content-Type application/json.
- Request Structure: Body contains
data(query condition object),pageNo(default 1),pageSize(default 10). - Response Structure: Standard JSON with a top-level
datalist. Each element containsid,number,name,status,createtime,modifytime, etc. Theresponsefield is auto-filled by the source-sideautoFillResponse; actual values depend on the API response. - Pagination Mode: Classic page-number pagination (
pageNo+pageSize), no cursor. - Incremental Mode: Relies on
modifytimeas the time-window increment. A common cron is*/3 7-23 * * *(every 3 minutes from 7am to 11pm daily). - Effect Flag: QUERY_ONLY — pure query with no target write, ideal for the upstream step of master data distribution.
Typical Field Mapping
| Field | Type | Meaning | Practical Notes |
|---|---|---|---|
| id | string | Sales order primary key | Stable anchor for cross-system mapping; treat as unique identifier |
| number | string | Document number (metadata maps to billno) | Business code used for reconciliation; watch out for Kingdee field renaming |
| name | string | Display name/title | Used in lists; may not match the customer name |
| status | string | Document status (draft/submitted/approved) | Common CRM filter |
| enable | string | Enable flag | Use to filter voided documents |
| createtime | string | Creation time | Secondary reference for incremental sync |
| modifytime | string | Last modification time | Preferred field for incremental sync; verify time zone |
| creator_id / modifier_id | string | Creator/modifier IDs | Used when mapping users across systems |
| createorg_number | string | Creating organization code | Kingdee's multi-org architecture; org dimension is mandatory |
| type | string | Document type | Different types follow different business flows |
| masterid | string | Master record ID | Used for master-detail linkage |
| ctrlstrategy | string | Control strategy flag | Sporadic field; defer to actual response |
| supplier_status_number / name | string | Supply status code and name | Used to track fulfillment progress; rely on actual API values |
Configuring on Qeasy
On the Qeasy Data Integration Platform, this type of Kingdee sales order query is typically handled with a "Kingdee Cloud Galaxy Flagship Edition adapter + empty-write Target" combination.
- Adapter Selection: The Qeasy adapter marketplace includes a built-in Kingdee Cloud Galaxy Flagship Edition connector that handles auth, tenant context, and pagination wrapping automatically.
- Field Mapper: The Qeasy field mapper automatically reads common fields like
id,number,name,status,createtime,modifytime, eliminating the need to manually assemble response structures. - Strategy Template: The Target is configured as "empty write", meaning this strategy only pulls sales orders into Qeasy's transit layer for consumption by downstream strategies that write to CRM or data warehouse.
- Scheduling: The cron
*/3 7-23 * * *covers business hours, leaving the early-morning window for backup and rerun.
Cross-Implementation Practical Points
- Dual anchor: id and number. Across multiple client projects we insist on using
idas the primary key andnumber(billno) as the business code — both are indispensable. - modifytime is the lifeline of incremental sync. Pagination plus time window is a reliable combination; page-only pagination tends to miss records.
- Never drop the organization dimension. Under Kingdee's multi-org architecture,
createorg_numbermust travel with the document; otherwise downstream data crosses organizations. - Supply status field names depend on the actual response. Although docs mention
supplier_status_number / name, different Kingdee versions may name them differently. Always capture a sample response before finalizing mapping. - Mark pure-query strategies as QUERY_ONLY. Setting Target to empty write avoids accidentally writing sales orders back to Kingdee and creating a loop.
- Business-hours scheduling. Skip early-morning runs to reduce conflict with Kingdee's nightly batch jobs.
Pitfall Recap
- Pitfall 1: Using number as id.
numberis the business code and may be adjusted in some scenarios; cross-system linkage must rely onid. - Pitfall 2: Ignoring time zones. Failing to convert
modifytimeshifts the incremental window, causing duplicate or missing pulls. - Pitfall 3: Supply status field name drift. Different Kingdee versions name the supply status fields inconsistently. The safe approach is to dump a real response before freezing the mapping.
- Pitfall 4: Default page size trap. The default
pageSizeof 10 is too small; explicitly enlarge it (e.g., 100) in production to cut request counts. - Pitfall 5: Cross-organization data leakage. Syncing without
createorg_numbercauses Organization A's documents to land in Organization B, which is extremely time-consuming to troubleshoot.
When to Use This API
Use this query API as the first choice when you need to sync Kingdee Cloud Galaxy Flagship Edition sales orders into a CRM, data middleware, or downstream system. If you need to write back to Kingdee, switch to a save-type API. If you only need lightweight validation, the built-in Kingdee reports are more cost-effective.