What This Interface Solves

In multi-store e-commerce operations, the shop is the core master data dimension for order aggregation, inventory allocation, logistics strategy, and electronic invoicing. The Wangdian Shop Query interface (shop WebAPI) is used to paginate and batch-pull shop basic information, supporting shop master data synchronization, mapping with Kingdee Cloud Xingchen organizations/customers, and accurate matching of orders/outbound orders by shop dimension. It serves as the "source master data strategy" in the supply chain integration chain.

Interface Capability Overview

Authentication: Based on the app_key (JSON containing key, secret, token) and refresh_token authorization system. Pay attention to four authorization lifecycle fields: auth_state, pay_auth_state, expire_time, re_expire_time.
Request Structure: POST request, body supports filtering by platform (platform ID) and shop_no (shop code).
Response Structure: Returns an array of shop objects, with each record containing 60+ fields covering basic information, platform authorization, administrative divisions, contact information, logistics strategy, and business switches.
Pagination Mode: page_no defaults to 0, page_size defaults to 40, range 1~~100. It is recommended to set 50~~80 in production environments to balance throughput and stability.
Incremental Mode: The API itself does not natively support incremental pulling by modified. A common approach is to use full sync first, then do delta sync based on local modification timestamps.

Typical Field Mapping

Field Name	Type	Meaning	Practical Notes
shop_id	string	Shop unique identifier, metadata id field	Cross-system primary key, recommended for direct ID mapping
shop_no	string	Shop code, customizable in ERP	Prefer shop_no for cross-system mapping for better business readability
shop_name	string	Shop name	Used for document display, watch for special characters and length truncation
platform_id	string	E-commerce platform identifier	Required parameter for multi-platform isolation
account_id / account_nick	string	Platform authorized account ID and nickname	Used to distinguish multiple accounts
auth_state	string	Authorization status (0 unauthorized/1 authorized/2 expired/3 disabled)	Must verify before integration, only sync shops with status 1
pay_auth_state	string	Alipay authorization status	Required for payment-related business
province/city/district + _name	string	Province/city/district ID and name	Store both ID and name redundantly for direct display
address / contact / mobile / telno / email	string	Contact information	Pay attention to desensitization, watch country for cross-border scenarios
logistics_id	string	Default logistics company ID	0 means calculated by logistics strategy
cod_logistics_id	string	Cash-on-delivery logistics company	Required for COD business
forbidden_logistics_list	string	Forbidden logistics list	JSON array format, handle with fault tolerance
is_disabled	string	Whether disabled	Reverse map with target system's enable field
modified / created	string	Modification/creation time	Auxiliary fields for incremental sync, requires local caching
great_deal_limit / great_deal_warehouse	string	Large order quantity limit and warehouse	Dedicated for large order business
is_setwarebygoods	string	Goods assignment method (0 none/1 warehouse/2 warehouse address)	Affects inventory allocation logic

How to Configure on Qeasy Cloud

On the Qeasy Cloud Data Integration Platform, Wangdian Shop Query typically uses a combination of source system adapter + QUERY_ONLY strategy. Select the Wangdian Enterprise adapter on the source side, configure app_key and token, then select the shop interface in the strategy editor. Qeasy Cloud's field mapper automatically reads the returned metadata, identifies shop_id as id and shop_no as number, saving manual annotation. On the Target side, select "Write Empty Operation" to complete the pure query strategy; if you need to sync shops to Kingdee Cloud Xingchen, add a downstream write strategy. Qeasy Cloud's visual field mapping supports drag-and-drop mapping of Wangdian fields to Xingchen's organization/customer profiles. Scheduled scheduling can directly use crontab */10 7-23 * * *, corresponding to the "every 10 minutes from 7:00-23:00 daily" configuration on the platform.

Cross-Scenario Practical Points

shop_id and shop_no Dual-Key Strategy: Use shop_id as the primary key for cross-system mapping to ensure uniqueness, and shop_no for business references to improve readability. Both approaches have been validated for stability.
Pre-filter Authorization Status: Discard shops with auth_state != 1 directly in Qeasy Cloud's source-side filter to avoid invalid data polluting downstream.
Don't Max Out Pagination Size: Although the interface supports up to 100, 60~80 is more stable in real scenarios. We've seen cases where 100 triggered rate limiting.
Redundant Storage of Administrative Divisions: Store both ID and name in the database, saving N+1 calls for downstream to look up basic information again.
Reverse Mapping for Disabled Field: Wangdian's is_disabled has opposite semantics to Kingdee's enable. Remember to check "negate" in the mapper.
Careful Mapping of Logistics Strategy Fields: logistics_id=0 means "calculated by strategy", do not blindly map it to a specific logistics company.

Pitfall Retrospective

Pitfall One: refresh_token Expiry Causes Empty Full Pull. The integration was running fine, but one day it suddenly returned an empty set. The cause turned out to be re_expire_time expiry triggering authentication failure. Solution: Qeasy Cloud's source-side connector has a token auto-refresh mechanism, but confirm the upstream has it enabled, and add an alert for "consecutive 2 cycles returning 0 records" in monitoring.
Pitfall Two: Shop Code Conflict After ERP Customization. Although shop_no is the code field, the ERP side allows users to manually change it. As a result, shops from two different platforms were changed to the same shop_no, causing mapping collisions. Solution: The safe approach is to use shop_id as the final primary key and shop_no only for auxiliary display.
Pitfall Three: forbidden_logistics_list Parsing Crashes Downstream. This field is a JSON array string. When encountering empty strings or invalid JSON, the downstream parser throws exceptions directly. Solution: Configure "safe parsing" + "exception default value" for this field in Qeasy Cloud's field mapper.
Pitfall Four: Administrative Division ID and Name Out of Sync. After Wangdian changed the province name, the ID remained the same but the name changed. When downstream matched by ID, it displayed the old name. Solution: It is recommended to also store the name field and use ID only as the association key.
Pitfall Five: is_disabled Reverse Mapping Missing. Shops disabled in Wangdian were still enabled after syncing to Kingdee, causing outbound orders to still be pushed down. Solution: Be sure to check "boolean negation" for this field in the mapper.

When to Use

Suitable for e-commerce multi-store scenarios where Wangdian shop master data needs to be synced to Kingdee Cloud Xingchen or other ERP/CRM systems as organization/customer profiles, supporting downstream supply chain businesses such as order aggregation, inventory allocation, logistics strategy, and electronic invoicing. Boundary: When the shop data volume is extremely large (tens of thousands or more) and near-real-time changes are needed, it is recommended to switch to Wangdian's push mechanism (push_rds_id) instead of polling.

Wangdian Shop Query (shop WebAPI) Field Handbook & Cross-Scenario Tutorial