Jushuitan Shop Query API Field Handbook: End-to-End Tutorial from Jushuitan to MySQL

What This Interface Solves

In multi-platform e-commerce scenarios, enterprises typically need a local copy of "shop master data" to split orders, inventory, and reports by shop, while also validating platform authorization. The Jushuitan Shop Query API serves exactly this purpose: it bulk-synchronizes shop profiles, group/company affiliations, and authorization session information from Jushuitan into a MySQL master-data table, providing the anchor key by which downstream business documents (orders, shipments, returns, purchase receipts, etc.) are aggregated per shop.

Interface Capabilities Overview

• Authentication: OAuth-based authorization via Jushuitan's open platform; access uses the resulting session credentials.
• Request structure: three parameters—page_index (default 1), page_size (default 100, max 100), and shop_ids (optional, filter by shop codes).
• Response structure: a shop list, where each record contains shop code, name, short name, primary account, site, URL, group, company, organization, session user, authorization expiration, and creation time.
• Pagination mode: standard pagination, max 100 records per page; iterate page_index linearly until the returned list is empty.
• Incremental mode: across multiple customer projects, we use a 2-hour cycle (crontab: 10 */2 * * *) with full overwrite pulls, writing to the MySQL target using shop_id as the unique key. Shop master data is small and rarely changes, so full replacement is far cheaper than delta reconciliation.

Typical Field Mappings

On the Qingyiyun data integration platform, the field mapper automatically maps these fields to MySQL columns under underscore naming conventions. The platform defaults to a REPLACE INTO write strategy keyed on shop_id, ensuring repeated pulls don't produce dirty data.

Configuring on Qingyiyun

1. Register the data source: add a Jushuitan adapter in Qingyiyun's "Data Sources", enter the credentials, and complete OAuth authorization.
2. Register the target source: add a MySQL data source pointing to the business database, and pre-create the target table jst_shops_query with shop_id as the primary key.
3. Adapter selection: choose the "Jushuitan · Shop Query" adapter, which already encapsulates pagination, incremental logic, and rate limiting.
4. Field mapping: in Qingyiyun's visual mapping interface, drag response fields to target columns one by one; the platform automatically handles type conversion and field-name normalization.
5. Schedule configuration: set the schedule to 10 */2 * * * (every 2 hours) and enable the "full overwrite write" switch so REPLACE INTO takes effect automatically.
6. Alerts and monitoring: configure retry, rate-limit alerts, and authorization-expiry reminders for this task in Qingyiyun's "Monitoring Center".

Cross-Scenario Practical Takeaways

1. Sync shops ahead of business documents: across multiple customer projects, we always set the shop sync schedule priority higher than orders, inventory, etc.—without shop_id in position, all downstream data grouped by shop becomes "orphan" data.
2. Full overwrite beats incremental: shop master data is small (typically hundreds to thousands of records) and changes infrequently, so full REPLACE INTO saves far more effort than delta reconciliation; the Qingyiyun field mapper supports this pattern natively.
3. Authorization expiry is a hidden landmine: session_expired may return the literal "------永久授权------"; handle this specially during mapping or persist it separately for manual review.
4. Multi-company/multi-shop requires co_id: in multi-legal-entity scenarios, co_id and group_id are critical for permission isolation and financial reporting—do not omit them.
5. Don't exceed the pagination cap: Jushuitan rejects requests with more than 100 records per page; the safe approach is to fix page_size=100 in Qingyiyun and let the platform paginate automatically.
6. shop_site IS the channel tag: downstream analytics typically slice data by shop_site, so standardize this field at the cleaning stage.

Pitfall Retrospective

1. shop_id overlaps with number/id: the response contains both number and id, both pointing to shop_id; mapping all three into the target causes primary-key conflicts. Keep only one target column.
2. session_expired literal breaks datetime loading: in permanent-auth scenarios, Jushuitan returns a special string; always add a "non-datetime → NULL" rule in Qingyiyun's field-cleaning rules.
3. Over-aggressive scheduling triggers rate limits: one customer set a 5-minute cycle and hit Jushuitan's rate limit; after changing to 2 hours the job stabilized. Minimum recommended interval is 30 minutes.
4. Missing primary key causes duplicate writes: without a unique index on shop_id, REPLACE INTO degrades to plain INSERT and data balloons rapidly. Always create the primary key first.
5. Shop sync lagging behind order sync breaks report consistency: orders are aggregated by unknown shop_id before shops arrive. Always schedule shop tasks before business-document tasks.

When to Use

Suitable for multi-platform e-commerce businesses that need per-shop data aggregation and permission isolation—especially multi-company/multi-shop setups sensitive to authorization validity, where downstream reports must split by channel/brand in supply-chain integration. The boundary: if there is only a single shop with no master-data reuse need, you can use the platform's native capabilities without local persistence; if the shop volume is extremely large (>100k records), evaluate the IO cost of full synchronization.