What Problem Does This API Solve

In e-commerce retail supply chains, sales returns are the most error-prone link: goods are returned from customers to the warehouse, generating a return stock-in bill in the WMS, which must then be synchronized to the ERP to form a stock-in voucher, reduce inventory, and trigger refunds. In the customer scenarios we have encountered, Wangdiantong Flagship Qimen handles front-end e-commerce orders and return fulfillment, while Kingdee Cloud Cosmos handles back-end finance and inventory accounting—the two systems must be connected at the return stage. This API (wdt.wms.stockin.refund.querywithdetail) is used to pull return stock-in master and detail data from Wangdiantong, serving as the standard entry point for building the "return → stock-in bill → inventory ledger" chain.

API Capability Overview

Authentication: Wangdiantong Qimen open platform uses AppKey + AppSecret signature mechanism. The Qeasy adapter has built-in signature assembly and timestamp verification, requiring no manual encryption logic.
Request Method: HTTP POST, JSON body.
Request Structure: pager (pagination, commonly page_no / page_size) + params (business parameters, such as time range, warehouse, status).
Response Structure: Outer response wrapping a data array and total_count. Master fields are flattened, with details in the details_list array which must be read in a loop.
Pagination / Incremental Mode: Typical page_size=50~100; incremental sync usually uses check_time or modified as watermark fields, filtering by created_time > last_sync_time.
Scheduled Task: Across multiple customer projects, we typically configure 24,54 * * * *, executing twice per hour to balance data freshness and API quota.

Typical Field Mapping

Field Name	Chinese Name	Type	Meaning	Practical Notes
order_no	Stock-in Order No.	string	Unique business number of return stock-in, primary key	Map directly to Kingdee FBillNo, enforce uniqueness check to prevent duplicate push
refund_no	Return Exchange No.	string	Associated return/exchange business number	Used for upstream return application tracing, cross-system association key
trade_no_list	Order Number	string	List of original sales order numbers	May be concatenated from multiple orders, split by delimiter then look up sales orders
warehouse_no	Warehouse Code	string	Warehouse business code	Map with Kingdee warehouse master data, ensure warehouse mapping table is maintained
warehouse_name	Warehouse Name	string	Warehouse name	Display and log aid only, do not write to Kingdee
status	Stock-in Status	string	Processing status	Only sync approved bills, filter unapproved status to avoid drift on Kingdee side
check_time	Approval Time	string	Approval pass time	Recommended as source for Kingdee FDate, more stable than created_time
created_time	Creation Time	string	Bill creation time	Common start watermark for incremental sync
modified	Last Modified Time	string	Last modification time	Incremental fallback field, captures status changes after approval
customer_no	Customer Code	string	Return customer code	Map to Kingdee customer master, build missing customers first
customer_name	Returner Name	string	Consignee name	Mask before writing to logs
shop_no	Shop Code	string	Shop business code	Map to Kingdee sales organization or shop master
shop_name	Shop Name	string	Shop name	Display only, avoid as master data key
shop_platform_id	Shop Platform ID	string	E-commerce platform shop identifier	Basis for distinguishing multi-platform (Tmall/Douyin/JD)
logistics_type	Logistics Method	string	Return logistics method	Text enum, note Kingdee field type
operator_name	Return Creator	string	Operator name	Usually not mapped, retained for audit
goods_count	Total Goods Count	string	Total return quantity	Cross-check with detail sum, alert on inconsistency
total_price	Total Stock-in Amount	string	Return total amount	Reconcile with sum of details
actual_refund_amount	Actual Refund Amount	string	Actual refund amount	Key financial reconciliation field, watch precision
shop_remark	Shop Remark	string	Shop-side remark	Long text, watch Kingdee field length
flag_name	Flag Name	string	Bill marker/color	Generally not mapped
details_list	Stock-in Details	array	Return line items array	Must be expanded to Kingdee FEntity body
spec_no	Spec Code	string	SKU code	One-to-one with Kingdee material code
goods_no	Goods Code	string	Goods code	Map to SKU master
spec_name	Spec Name	string	SKU name	Display only
num	Quantity	string	Return quantity	String type, convert to numeric
price	Unit Price	string	Return unit price	Watch precision, unify to 2 decimals
amount	Amount	string	Line amount	Reconcile with num*price

How to Configure on Qeasy

Qeasy Data Integration Platform has a built-in Wangdiantong Qimen adapter—simply select Wangdiantong Qimen as the data source and fill in AppKey and AppSecret to complete authentication. The platform wraps the request template for wdt.wms.stockin.refund.querywithdetail by default. The field mapper automatically expands the details_list array and splits it into bill header and bill body according to the Kingdee KD_OMS_InBill form structure. For incremental strategy, the platform supports both check_time based time watermark mode and modified based offset mode, switchable directly in the strategy config page. Error retry, breakpoint resume, and rate limiting are managed by the platform. In real scenarios, we usually set batch size to 50, which both fills pagination and staggers API throttling.

Cross-Scenario Practical Points

Primary Key Selection: Always use order_no as the idempotency key—any sync logic must dedupe by order_no first. Do not use refund_no directly, since the same return/exchange may produce multiple stock-in bills in batches.
Approval Status Filter: Only sync bills with status "approved"; otherwise Kingdee will receive draft data that may be withdrawn or modified.
Time Watermark Fallback: Record both check_time and modified—the former for regular incremental, the latter for capturing boundary scenarios where modifications occur after approval.
Detail Reconciliation: Before landing, validate sum(details_list.amount) against total_price, and write alerts for discrepancies beyond threshold.
Master Data Pre-establishment: Warehouse, shop, customer, and SKU masters must exist on the Kingdee side first, otherwise bills will be rejected due to missing foreign keys.
Multi-Platform Distinction: Distinguish Tmall, Douyin, JD and other channels via shop_platform_id to avoid cross-channel mix-ups in downstream statistics.

Pitfall Recap

Unexpanded Details: The source system's details_list is an array. Direct mapping to Kingdee will produce a single-field JSON string—must loop and expand into multi-line FEntity in the mapper.
Precision Loss in String Number Summation: num, price, and amount are all strings. Direct addition yields 1+2=12. Convert via parseFloat and control decimal places before summation.
Timezone Drift: Wangdiantong timestamps are UTC+8 strings. After importing to Kingdee, timezone mismatch may cause date crossover. The safe approach is to explicitly parse with timezone.
Return Exchange vs Stock-in Confusion: refund_no is the return/exchange business number, while order_no is the stock-in number. Beginners often push refund_no to Kingdee as primary key, causing duplicate bills.
Quota and Throttling: High-frequency full scans easily trigger Wangdiantong API rate limits. The safe approach is fixed 50 records per page, twice per hour, with exponential backoff on failure.

When to Use

This API is suitable for the standard e-commerce retail return chain where Wangdiantong handles front-end fulfillment and Kingdee handles back-end accounting. It is not suitable for pure offline retail returns, P2P transfer returns, or lightweight summary scenarios without detail requirements. If returns do not involve stock-in (refund only), switch to the return/exchange order query API instead.

Sales Return Order Query API Field Handbook: Authoritative Tutorial for Wangdiantong and Kingdee Cloud Cosmos Integration