Authoritative Tutorial: Kingdee Xinghan Sales Order Query API Field Manual
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, wherea123is 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 includebillstatus,bizdaterange, andmodifytimerange). - Response Structure: List-type, where each record represents an entire document.
billnoandidare exposed in metadata asnumberandid.idCheck: trueenables primary key validation;autoFillResponse: truelets response fields auto-align with the metadata. - Pagination and Incremental: Pagination advances via
pageNo/pageSize; incremental usesmodifytimeas the timestamp cursor. The safe approach is to run multiple times per day (in this case crontab0-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 Name | Type | Meaning | Practical Notes |
|---|---|---|---|
| id | string | Kingdee system primary key | Cross-system primary key used for deduplication and reverse lookup |
| billno | string | Document number | Primary key for cross-system linking; often mapped to the e-commerce-side order number |
| billstatus / billstatus_title | string | Document status / display name | Downstream outbound and invoicing only act on values like "Audited" |
| closestatus / closestatus_title | string | Close status | Closed orders no longer drive outbound |
| cancelstatus / canceldate | string | Cancel status and date | Canceled orders must be explicitly filtered downstream |
| auditdate | string | Audit date | One of the common anchors for incremental sync |
| modifytime | string | Last modification time | Preferred anchor for incremental sync |
| bizdate / biztime | string | Business date / time | Evidence for financial posting date |
| totalamount / totaltaxamount / totalallamount | string | Tax-exclusive amount / tax amount / price-tax total | Transmitted as strings; must be parsed into decimals for reconciliation |
| curtotalamount / curtotalallamount | string | Book currency amount | Mandatory in multi-currency scenarios |
| exchangerate / exratedate / exchangetype | string | Exchange rate / applicable date / type | Used for verifying cost on foreign-currency orders |
| receiveaddress / address | string | Receiving address / business address | Key fields for logistics integration |
| deliverlocation | string | Delivery location / warehouse | Determines warehouse assignment |
| a123_textfield* / a123_datefield* / a123_decimalfield* / a123_combofield* | string | Tenant-defined extension fields | Meaning 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:
- Create Strategy → Select Kingdee Xinghan → Choose "Sales Order Query" adapter; the system pre-fills the request path and default pagination parameters.
- Metadata Alignment: Map
billnotonumber,idtoid, enableidCheck. The platform automatically deduplicates by primary key. - Incremental Strategy: In Qeasy Cloud's timestamp scheduler, use
modifytimeas the incremental cursor. The safe approach is to addbizdateas a fallback filter to prevent historical dirty data from being pulled repeatedly. - 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.
- Filter Conditions: Pass
billstatus=A(Audited) orclosestatus=in thedataparameter; the platform automatically translates these expressions into Kingdee-side query semantics. - Custom Fields: Extension fields with the
a123prefix 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
billnois the lifeline of cross-system linking. Between Kingdee and the retail ERP, the order number (corresponding to the retail ERP'stid/oid) must align precisely withbillno; otherwise, "duplicate orders for the same business" reconciliation black holes will appear.- Prefer
modifytimeas the incremental cursor. Compared withauditdate,modifytimecaptures 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. - Consume status fields as a group:
billstatus(audit),closestatus(close), andcancelstatus(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. - Convert all amount fields to decimal: Kingdee returns amounts as strings; doing subtraction directly will overflow. The integration side must explicitly parse them.
- 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.
- Interpret custom fields per tenant: The
a123extension 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_titleas a judgment condition.titleis a display name that may be localized or have copy changed. The safe approach is to only use coded fields likebillstatusfor logical judgment. - Pitfall 2: Setting
pageSizeto 50/100 causing OOM. Kingdee documents are large; a largepageSizewill cause the response body to blow up memory. The safe approach is pageSize ≤ 20, paired with high-frequency retries. - Pitfall 3: Using
createtimeas the incremental start point causes full historical reload.createtimedoes not reflect subsequent changes. The safe approach ismodifytimeas primary,bizdateas secondary. - Pitfall 4: Missing exchange rate fields causes financial amount mismatch. For foreign-currency orders, both
exchangerateandexratedatemust be landed; do not take onlytotalamount. - Pitfall 5: Missing close/cancel status filter causes duplicate outbound triggering. If the downstream system does not consume
closestatusandcancelstatus, 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).