Qeasy Cloud
Get Started

Authoritative Tutorial: Kingdee Xinghan Sales Order Query API Field Manual

· 许创贵· Engineering Best Practices· 22 views· 5 min read

What Problem Does This Interface Solve

In retail and omni-channel scenarios, the e-commerce front-end (corresponding to a typical retail ERP in this case) generates massive volumes of sales orders every day. These orders must flow back to the Kingdee Xinghan supply chain side for review, outbound, invoicing, and business-finance reconciliation. This interface, /kapi/v2/a123/sm/sm_salorder/getOrder, is used to query sales order master data from Kingdee Xinghan. Its typical value: providing an authoritative document source for cross-system order reconciliation, supporting incremental synchronization of audited orders, and supplying ready-status orders for downstream outbound and invoicing.

Interface Capability Overview

  • Authentication: Kingdee Xinghan open platform standard OAuth/Token model. In Qeasy Cloud, credentials are uniformly managed through connectors, so no hard-coding is required in scripts.
  • Request Path: /kapi/v2/a123/sm/sm_salorder/getOrder, where a123 is the tenant/application prefix and should be replaced according to the actual environment.
  • Request Structure: pageNo (default 1), pageSize (default 20), data (filter condition object; typical filter dimensions include billstatus, bizdate range, and modifytime range).
  • Response Structure: List-type, where each record represents an entire document. billno and id are exposed in metadata as number and id. idCheck: true enables primary key validation; autoFillResponse: true lets response fields auto-align with the metadata.
  • Pagination and Incremental: Pagination advances via pageNo/pageSize; incremental uses modifytime as the timestamp cursor. The safe approach is to run multiple times per day (in this case crontab 0-59/5 7-22 * * *, every 5 minutes) to reduce single-call timeout and missing-record risk.
  • Execution Frequency: Every 5 minutes from 7:00 to 22:00 daily; high-frequency pulls during business peaks, leaving the early-morning window for upstream write operations.

Typical Field Mapping

Field NameTypeMeaningPractical Notes
idstringKingdee system primary keyCross-system primary key used for deduplication and reverse lookup
billnostringDocument numberPrimary key for cross-system linking; often mapped to the e-commerce-side order number
billstatus / billstatus_titlestringDocument status / display nameDownstream outbound and invoicing only act on values like "Audited"
closestatus / closestatus_titlestringClose statusClosed orders no longer drive outbound
cancelstatus / canceldatestringCancel status and dateCanceled orders must be explicitly filtered downstream
auditdatestringAudit dateOne of the common anchors for incremental sync
modifytimestringLast modification timePreferred anchor for incremental sync
bizdate / biztimestringBusiness date / timeEvidence for financial posting date
totalamount / totaltaxamount / totalallamountstringTax-exclusive amount / tax amount / price-tax totalTransmitted as strings; must be parsed into decimals for reconciliation
curtotalamount / curtotalallamountstringBook currency amountMandatory in multi-currency scenarios
exchangerate / exratedate / exchangetypestringExchange rate / applicable date / typeUsed for verifying cost on foreign-currency orders
receiveaddress / addressstringReceiving address / business addressKey fields for logistics integration
deliverlocationstringDelivery location / warehouseDetermines warehouse assignment
a123_textfield* / a123_datefield* / a123_decimalfield* / a123_combofield*stringTenant-defined extension fieldsMeaning varies by tenant; interpret according to actual configuration

How to Configure on Qeasy Cloud

In the Qeasy Cloud Data Integration Platform, this interface is typically encapsulated as a Kingdee Xinghan connector. The typical configuration path:

  1. Create Strategy → Select Kingdee Xinghan → Choose "Sales Order Query" adapter; the system pre-fills the request path and default pagination parameters.
  2. Metadata Alignment: Map billno to number, id to id, enable idCheck. The platform automatically deduplicates by primary key.
  3. Incremental Strategy: In Qeasy Cloud's timestamp scheduler, use modifytime as the incremental cursor. The safe approach is to add bizdate as a fallback filter to prevent historical dirty data from being pulled repeatedly.
  4. Target Configured as No-Op: This case is a pure query strategy with no write to the target system. The Qeasy Cloud field mapper can disable write actions and only land or forward data.
  5. Filter Conditions: Pass billstatus=A (Audited) or closestatus= in the data parameter; the platform automatically translates these expressions into Kingdee-side query semantics.
  6. Custom Fields: Extension fields with the a123 prefix are automatically recognized by Qeasy Cloud's field mapper; no manual supplementation is needed; simply drag them to the target side.

Cross-Scenario Practical Essentials

  1. billno is the lifeline of cross-system linking. Between Kingdee and the retail ERP, the order number (corresponding to the retail ERP's tid/oid) must align precisely with billno; otherwise, "duplicate orders for the same business" reconciliation black holes will appear.
  2. Prefer modifytime as the incremental cursor. Compared with auditdate, modifytime captures all write actions including change orders and resubmissions. The safe approach is to set the window to "last successful time − 1 minute" to prevent missed records.
  3. Consume status fields as a group: billstatus (audit), closestatus (close), and cancelstatus (cancel) must be judged jointly. Looking at only one field is a common pitfall that can lead to outbound being triggered for already-closed orders.
  4. Convert all amount fields to decimal: Kingdee returns amounts as strings; doing subtraction directly will overflow. The integration side must explicitly parse them.
  5. Increase execution density during peak hours: This case compresses the execution window to every 5 minutes from 7:00 to 22:00, aligning with business rhythm while avoiding early-morning upstream ETL.
  6. Interpret custom fields per tenant: The a123 extension fields are configured by each tenant as needed. When taking over an unfamiliar tenant, always grab samples first to verify meanings; do not copy another tenant's scheme verbatim.

Pitfall Retrospective

  • Pitfall 1: Using billstatus_title as a judgment condition. title is a display name that may be localized or have copy changed. The safe approach is to only use coded fields like billstatus for logical judgment.
  • Pitfall 2: Setting pageSize to 50/100 causing OOM. Kingdee documents are large; a large pageSize will cause the response body to blow up memory. The safe approach is pageSize ≤ 20, paired with high-frequency retries.
  • Pitfall 3: Using createtime as the incremental start point causes full historical reload. createtime does not reflect subsequent changes. The safe approach is modifytime as primary, bizdate as secondary.
  • Pitfall 4: Missing exchange rate fields causes financial amount mismatch. For foreign-currency orders, both exchangerate and exratedate must be landed; do not take only totalamount.
  • Pitfall 5: Missing close/cancel status filter causes duplicate outbound triggering. If the downstream system does not consume closestatus and cancelstatus, duplicate shipments will occur, which is the most common source of cash and fulfillment incidents in real projects.

When to Use

This interface is suitable for querying sales order master data in "e-commerce front-end ↔ Kingdee Xinghan supply chain" scenarios, especially for cross-system order reconciliation, incremental sync of audited orders, and driving downstream outbound/invoicing chains. It is not suitable for write scenarios to Kingdee (which is the domain of saveOrder-type interfaces), nor for real-time single-point queries (high-frequency polling scenarios should use change notifications).

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

Comments