Qeasy Cloud
Get Started

Kingdee Cloud Galaxy Flagship Edition - Sales Order Query API Field Handbook Tutorial

· 吕修远· Engineering Best Practices· 14 views· 4 min read
小满OKKICRM金蝶云·星空旗舰版金蝶云·星空销售订单接口字段手册轻易云Incremental SyncData Integration

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 data list. Each element contains id, number, name, status, createtime, modifytime, etc. The response field is auto-filled by the source-side autoFillResponse; actual values depend on the API response.
  • Pagination Mode: Classic page-number pagination (pageNo + pageSize), no cursor.
  • Incremental Mode: Relies on modifytime as 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

FieldTypeMeaningPractical Notes
idstringSales order primary keyStable anchor for cross-system mapping; treat as unique identifier
numberstringDocument number (metadata maps to billno)Business code used for reconciliation; watch out for Kingdee field renaming
namestringDisplay name/titleUsed in lists; may not match the customer name
statusstringDocument status (draft/submitted/approved)Common CRM filter
enablestringEnable flagUse to filter voided documents
createtimestringCreation timeSecondary reference for incremental sync
modifytimestringLast modification timePreferred field for incremental sync; verify time zone
creator_id / modifier_idstringCreator/modifier IDsUsed when mapping users across systems
createorg_numberstringCreating organization codeKingdee's multi-org architecture; org dimension is mandatory
typestringDocument typeDifferent types follow different business flows
masteridstringMaster record IDUsed for master-detail linkage
ctrlstrategystringControl strategy flagSporadic field; defer to actual response
supplier_status_number / namestringSupply status code and nameUsed 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

  1. Dual anchor: id and number. Across multiple client projects we insist on using id as the primary key and number (billno) as the business code — both are indispensable.
  2. modifytime is the lifeline of incremental sync. Pagination plus time window is a reliable combination; page-only pagination tends to miss records.
  3. Never drop the organization dimension. Under Kingdee's multi-org architecture, createorg_number must travel with the document; otherwise downstream data crosses organizations.
  4. 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.
  5. Mark pure-query strategies as QUERY_ONLY. Setting Target to empty write avoids accidentally writing sales orders back to Kingdee and creating a loop.
  6. Business-hours scheduling. Skip early-morning runs to reduce conflict with Kingdee's nightly batch jobs.

Pitfall Recap

  • Pitfall 1: Using number as id. number is the business code and may be adjusted in some scenarios; cross-system linkage must rely on id.
  • Pitfall 2: Ignoring time zones. Failing to convert modifytime shifts 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 pageSize of 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_number causes 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.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/engineering/hb-p2-129-7840

Comments