Authoritative Tutorial on the Kingdee Xinghan Sales Price List Query Interface Field Manual

What This Interface Solves

In retail and distribution scenarios, price is the most sensitive field outside of orders and inventory. With WDT as the front-end retail system and Kingdee Xinghan as the back-end supply chain/finance system, the two must align pricing across the three dimensions of "material × customer × date". The Sales Price List interface pulls price list data (master + detail rows) from the Kingdee Xinghan side on demand for: ① synchronizing sales pricing rules; ② matching WDT product prices against Kingdee price lists item by item; ④ retrieving standard prices during order quotation; ⑤ mapping customer-level pricing policies.

Interface Capability Overview

• Endpoint: /kapi/v2/a123/sm/sm_salepricelist/sale_price
• Request Method: HTTP POST (query interface), JSON body with pagination and filter conditions
• Authentication: Tenant-level token (Header authentication); tokens are managed and refreshed by the Qeasy scheduling layer
• Request Parameters: pageNo (default 1), pageSize (default 20), data (optional filter object supporting material/customer/date conditions)
• Response Structure: Array-type list; each record is a composite object of price list + detail rows, containing master fields and priceentryentity_* detail fields
• Pagination: Standard pageNo/pageSize pagination, cursor not supported
• Incremental Mode: Relies on modifytime (modification time) for incrementals; primary key id is actually concatenated as {{modifytime}}{{id}}{{priceentryentity_id}} for unique deduplication of master + detail rows
• Execution Frequency: crontab 1-59/5 7-22 * * *, every 5 minutes during business hours
• Write Strategy: Target is "empty operation" — a pure query strategy that lands data into the Qeasy middle platform

Typical Field Mappings

How to Configure on Qeasy

On the Qeasy Data Integration Platform, this interface is typically accessed using three components: "Kingdee Xinghan Adapter + Field Mapper + Empty Operation Target":

1. Adapter Selection: Qeasy has a built-in Kingdee Xinghan (kapi v2) adapter; just fill in the tenant code, account set number (token is managed by the platform, no manual maintenance required), and target endpoint path.
2. Pagination and Filtering: pageNo/pageSize can be configured directly in the adapter panel; data filter conditions support drag-and-drop field generation.
3. Field Mapper: The Qeasy field mapper automatically reads interface metadata and one-click maps the fields above to the target middle platform model; idCheck is enabled by default, and the primary key concatenation rule can be written directly in metadata as {{modifytime}}{{id}}{{priceentryentity_id}}.
4. Incremental Watermark: The platform automatically maintains incremental cursors based on modifytime, no need to manually write SQL to record watermarks; checkpoint resumption is also handled by the platform.
5. Empty Operation Target: Select "Empty Operation" for the Target; data landing into Qeasy middle platform is considered successful without writing back to Kingdee, avoiding misoperations.

Cross-Scenario Practical Highlights

Across multiple customer projects, we repeatedly run into the following common issues. The proven approaches are:

1. Primary Key Must Be Composite: Price lists have a "master + detail row" two-layer structure; using id alone inevitably causes collisions. Always concatenate modifytime+id+priceentryentity_id.
2. Pre-filter Status: Filter status=A (audited) and enable=1 (enabled) on the request side or in the mapper; otherwise downstream data will be polluted by draft/disabled records.
3. Validity Check: effectdate ≤ now ≤ expirydate must be re-validated after landing; the interface only provides raw values and does not make judgments for you.
4. Tax-inclusive Price Separation: istax determines whether the price field is tax-inclusive. When persisting, split into three columns: "tax-inclusive price", "tax-exclusive price", "tax rate". This avoids errors in downstream finance modules.
5. Expand Tiered Pricing: When isstair=1, price information is hidden in the priceentryentity_* sub-table; detail rows must be loop-expanded before pricing.
6. Customer-level Mapping: Build a mapping table between applycustomer and WDT customers/membership tiers. Match by customer priority during pricing — far more reliable than hardcoding.

Troubleshooting Retrospective

• Pitfall 1: Primary key collisions causing data loss. Using only id as the primary key causes multiple material detail rows under the same price list to be overwritten. Fix: enable idCheck and generate primary keys per the concatenation rule.
• Pitfall 2: Incremental watermark disrupted by retroactive edits. Kingdee supports un-audit and price modification; modifytime rolls back and the incremental cursor "misses pulls". Fix: add a compensation condition audittime > last watermark, or do a daily full reconciliation.
• Pitfall 3: Tax-inclusive price used as tax-exclusive. Price retrieval during ordering is normal, but tax/price amounts don't match during invoicing. Fix: split by istax when landing; downstream takes what it needs.
• Pitfall 4: Draft records pollute downstream. Without filtering status, draft price lists also get synced to the front end. Fix: add status filtering on the request side, or add branching in the mapper.
• Pitfall 5: Only the first row is taken for tiered pricing. Detail rows contain multiple quantity ranges; taking only the first one causes low prices for large quantities. Fix: loop-match by quantity range; the Qeasy mapper supports script extensions.

When to Use

This interface suits retail/distribution scenarios where "Kingdee Xinghan price list is the single source of truth for pricing" — especially WDT+Kingdee hybrid deployments with front-end needs for fine-grained quotation by material + customer + date, and strong requirements for tax-inclusive/tiered pricing. The boundary: suitable for query-only scenarios; if external prices need to be written back into Kingdee, a separate write-type interface is required.