Shopify 店铺数据抓取 API

Response notes

- Returns the requested storefront URL plus the resolved source URL used for JSON requests. - Includes `myshopify_domain`, store name, currency, country, and published product/collection counts when `/meta.json` exposes them. - Blocked pages, malformed JSON, missing Shopify roots, and unavailable fallback domains return upstream errors. - If the classic `/products.json` endpoint and `*.myshopify.com` domain resolution are both unavailable (some headless Next.js/React storefronts on a Shopify catalog do not expose either), the service falls back to fetching the storefront's own pages directly and parsing their embedded structured data. When this fallback was used, `transport_mode` is `ssr_embedded`; it is omitted entirely for stores served by the classic catalog JSON. Fallback-mode responses may have fewer populated fields (for example `myshopify_domain` and the `/meta.json`-sourced fields are typically unavailable) since `/meta.json` is also unavailable on these storefronts. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport). Example response: ```json { "code": 200, "msg": "OK", "data": { "requested_url": "https://www.allbirds.com", "source_url": "https://www.allbirds.com", "domain": "www.allbirds.com", "source_domain": "www.allbirds.com", "name": "Allbirds", "currency": "USD", "country": "US", "published_products_count": 638 } } ```

Response notes

- Valid empty result pages return `200` with an empty `products` array. - Product prices are normalized to decimal currency units. - Blocked pages, malformed JSON, and missing `products` roots return upstream errors. - If the classic `/products.json` endpoint and `*.myshopify.com` domain resolution are both unavailable (some headless Next.js/React storefronts on a Shopify catalog do not expose either), the service falls back to the storefront's own conventional "all products" collection page (`/collections/all`) and parses its embedded search-result payload. When this fallback was used, the response includes `transport_mode: "ssr_embedded"`, `total_items`, and `total_pages` (the storefront's own result-count/page-count metadata), and each product may include additive fields only available from this source: `colour`, `canonical_colour`, `discount_percentage`, `rating`, `rating_count`, `collection_tags`, `labels`, and per-variant `inventory_quantity`. `limit` is still honored as an upper bound on returned items, but the underlying page size is fixed by the storefront (commonly 60) and cannot be requested larger than that in fallback mode. `transport_mode`, `total_items`, and `total_pages` are omitted entirely for stores served by the classic catalog JSON. - When the `ssr_embedded` fallback was used, the response may also include `facets` and `facets_stats`, mirroring the storefront's own filter sidebar for that listing: `facets` maps a facet field name exactly as the storefront names it (for example `fit`, `activities`, `canonicalColour`, `sizeInStock`) to its value-to-count buckets, and `facets_stats` gives `min`/`max`/`avg` for numeric-range fields such as `price` and `discountPercentage`. Both are omitted when the storefront's payload did not include facet data, and always omitted for the classic transport. - **Sort and filters are SSR-fallback only.** Shopify's classic public `/products.json` catalog feed has no server-side sort or filter support at all — confirmed live: requesting the same store's classic JSON with a sort applied returns byte-identical product order to the unsorted request. Rather than silently accepting and ignoring `sortBy` or a facet filter against a classic-transport store (which would look like it worked but wouldn't), this endpoint rejects the request with a `400` invalid-param error whenever `sortBy` or any facet-filter query param is supplied and the resolved store is not `transport_mode: "ssr_embedded"`. - When a sort and/or filters were applied on the SSR-fallback transport, the response echoes back what was actually honored: `sort` (one of the enum values below) and `filters` (a map of facet field name to the array of values that were requested for it, after comma-splitting). Both are omitted when no sort/filter was supplied. - `hitsPerPage` (the storefront's own listing page size, commonly 60) is unaffected by sort/filters; `limit` continues to apply as an upper bound on the returned page. `sortBy` allowed values: `sortLTH`, `sortHTL`, `newest`. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport). Example response: ```json { "code": 200, "msg": "OK", "data": { "store_url": "https://www.allbirds.com", "source_url": "https://www.allbirds.com", "page": 1, "limit": 2, "products": [ { "id": "7188363542608", "handle": "mens-tree-runner-nz-natural-white", "title": "Men's Tree Runner NZ - Natural White (Natural White Sole)", "url": "https://www.allbirds.com/products/mens-tree-runner-nz-natural-white", "price": 100, "available": true } ] } } ```

Response notes

- Product prices from `.js` responses are normalized from cent values to decimal currency units. - Missing product handles return `404` when Shopify returns not found. - Blocked pages, malformed JSON, and missing product fields return upstream errors. - If the classic product `.js` endpoint and `*.myshopify.com` domain resolution are both unavailable (some headless Next.js/React storefronts on a Shopify catalog do not expose either), the service falls back to fetching the product detail page directly and parsing its embedded structured data — preferring a richer Next.js data block when the storefront exposes one, and falling back further to the page's schema.org JSON-LD `ProductGroup`/`Product` block otherwise. When this fallback was used, the response includes `transport_mode: "ssr_embedded"`, and the product may include additive fields only available from this source: `colour`, `canonical_colour`, `discount_percentage`, `rating`, `rating_count`, `collection_tags`, `labels`, and per-variant `inventory_quantity`. `transport_mode` is omitted entirely for stores served by the classic product `.js` endpoint. A product page that carries neither the richer data block nor a matching JSON-LD block returns an upstream error. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport). Example response: ```json { "code": 200, "msg": "OK", "data": { "store_url": "https://www.allbirds.com", "source_url": "https://www.allbirds.com", "product": { "id": "7188363542608", "handle": "mens-tree-runner-nz-natural-white", "title": "Men's Tree Runner NZ - Natural White (Natural White Sole)", "price": 100, "images": [{"url": "https://cdn.shopify.com/example.jpg"}] } } } ```

Response notes

- Missing product handles return `404` when Shopify returns not found while resolving the seed product. - Valid empty recommendation arrays return `200` with an empty `products` array. - Blocked pages, malformed JSON, and missing Shopify roots return upstream errors. - If the classic recommendations endpoint and `*.myshopify.com` domain resolution are both unavailable (some headless Next.js/React storefronts on a Shopify catalog do not expose either), the service falls back to fetching the seed product's own detail page (recommendations are embedded there) and parses its embedded recommendation carousels. When this fallback was used, the response includes `transport_mode: "ssr_embedded"`, and each product may include the same additive fields documented for `/shopify/products`: `colour`, `canonical_colour`, `discount_percentage`, `rating`, `rating_count`, `collection_tags`, `labels`, and per-variant `inventory_quantity`. `transport_mode` is omitted entirely for stores served by the classic endpoint. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport).

Response notes

- Valid empty result pages return `200` with an empty `collections` array. - Blocked pages, malformed JSON, and missing `collections` roots return upstream errors. - If the classic `/collections.json` endpoint and `*.myshopify.com` domain resolution are both unavailable (some headless Next.js/React storefronts on a Shopify catalog do not expose either), the service falls back to enumerating collections from the storefront's own `collections` sitemap. When this fallback was used, the response includes `transport_mode: "ssr_embedded"`, and `title` is a best-effort derivation from the handle (hyphens become spaces, each word title-cased) — **not** the storefront's real display name, since no other source for it exists in this mode. `products_count` and other classic-only fields are omitted, never fabricated. `transport_mode` is omitted entirely for stores served by the classic catalog JSON. - In this fallback mode, `handle` is derived from the last path segment of the collection URL and is not guaranteed unique: some storefronts nest gender/audience-scoped sub-collections under the same final segment (for example `/collections/all-products/womens` and `/collections/legacy/womens` both derive `handle: "womens"`). Use the item's own `url` to identify a specific nested collection rather than assuming `handle` alone round-trips through `GET /shopify/collections/{handle}/products`. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport). Example response: ```json { "code": 200, "msg": "OK", "data": { "store_url": "https://www.allbirds.com", "source_url": "https://www.allbirds.com", "page": 1, "limit": 2, "collections": [ { "id": "278435758160", "handle": "mens", "title": "Men", "url": "https://www.allbirds.com/collections/mens", "products_count": 24 } ] } } ```

Response notes

- Valid empty result pages return `200` with an empty `products` array. - Missing collections return `404` when Shopify returns not found. - Blocked pages, malformed JSON, and missing `products` roots return upstream errors. - If the classic collection `/products.json` endpoint and `*.myshopify.com` domain resolution are both unavailable (some headless Next.js/React storefronts on a Shopify catalog do not expose either), the service falls back to fetching the collection listing page directly (`/collections/{handle}`) and parsing its embedded search-result payload. When this fallback was used, the response includes `transport_mode: "ssr_embedded"`, `total_items`, and `total_pages` (the storefront's own result-count/page-count metadata), and each product may include additive fields only available from this source: `colour`, `canonical_colour`, `discount_percentage`, `rating`, `rating_count`, `collection_tags`, `labels`, and per-variant `inventory_quantity`. `limit` is still honored as an upper bound on returned items, but the underlying page size is fixed by the storefront (commonly 60) and cannot be requested larger than that in fallback mode. `transport_mode`, `total_items`, and `total_pages` are omitted entirely for stores served by the classic catalog JSON. - When the `ssr_embedded` fallback was used, the response may also include `facets` and `facets_stats`, mirroring the collection page's own filter sidebar: `facets` maps a facet field name exactly as the storefront names it (for example `fit`, `activities`, `canonicalColour`, `sizeInStock`) to its value-to-count buckets, and `facets_stats` gives `min`/`max`/`avg` for numeric-range fields such as `price` and `discountPercentage`. Both are omitted when the storefront's payload did not include facet data, and always omitted for the classic transport. - **Sort and filters are SSR-fallback only.** Shopify's classic public collection `/products.json` catalog feed has no server-side sort or filter support at all — confirmed live: requesting the same store's classic JSON with a sort applied returns byte-identical product order to the unsorted request. Rather than silently accepting and ignoring `sortBy` or a facet filter against a classic-transport store (which would look like it worked but wouldn't), this endpoint rejects the request with a `400` invalid-param error whenever `sortBy` or any facet-filter query param is supplied and the resolved store is not `transport_mode: "ssr_embedded"`. - When a sort and/or filters were applied on the SSR-fallback transport, the response echoes back what was actually honored: `sort` (one of the enum values below) and `filters` (a map of facet field name to the array of values that were requested for it, after comma-splitting). Both are omitted when no sort/filter was supplied. - `hitsPerPage` (the storefront's own listing page size, commonly 60) is unaffected by sort/filters; `limit` continues to apply as an upper bound on the returned page. `sortBy` allowed values: `sortLTH`, `sortHTL`, `newest`. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport). Example response: ```json { "code": 200, "msg": "OK", "data": { "store_url": "https://www.allbirds.com", "source_url": "https://www.allbirds.com", "collection": "mens", "page": 1, "limit": 2, "products": [ { "handle": "mens-dasher-nz-ochre", "title": "Men's Tree Dasher 2", "price": 135 } ] } } ```

Response notes

- Products and collections are normalized to the same shapes used by the Shopify product and collection endpoints. - Query suggestions include text and a storefront search URL when Shopify provides one. - Valid empty suggestion arrays return `200` with empty arrays. - Blocked pages, malformed JSON, and missing Shopify roots return upstream errors.

Response notes

- Page content is cleaned text from Shopify `body_html`; raw HTML is not returned. - Valid empty page arrays return `200` with an empty `pages` array. - Blocked pages, malformed JSON, and missing Shopify roots return upstream errors. - If the classic `/pages.json` endpoint and `*.myshopify.com` domain resolution are both unavailable (some headless Next.js/React storefronts on a Shopify catalog do not expose either), the service falls back to enumerating page handles from the storefront's own `pages` sitemap. When this fallback was used, the response includes `transport_mode: "ssr_embedded"`, and each item only carries `handle`, `url`, and `updated_at` — no `title`, `id`, or `content`. Call `GET /shopify/pages/{handle}` per handle to get full content; this trade-off avoids an unbounded per-page fetch fan-out for large stores. `transport_mode` is omitted entirely for stores served by the classic catalog JSON. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport).

Response notes

- Page content is cleaned text from Shopify `body_html`; raw HTML is not returned. - Missing page handles return `404` when Shopify returns not found. - Blocked pages, malformed JSON, and missing Shopify roots return upstream errors. - If the classic `/pages/{handle}.json` endpoint and `*.myshopify.com` domain resolution are both unavailable (some headless Next.js/React storefronts on a Shopify catalog do not expose either), the service falls back to fetching the page's own HTML and parsing an embedded Contentful CMS entry. When this fallback was used, the response includes `transport_mode: "ssr_embedded"`; `content` is plain text rendered from the page's Contentful rich-text blocks (marks/formatting are dropped, non-rich-text blocks such as banners are skipped), and `id` is omitted because the source id is a Contentful entry id, not a Shopify numeric id. `transport_mode` is omitted entirely for stores served by the classic endpoint. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport).

Response notes

- Sitemap `type` is inferred from the child sitemap URL. - Inferred sitemap types are `products`, `collections`, `pages`, `blogs`, `agentic_discovery`, and `other`. - Blocked pages, malformed XML, and missing sitemap entries return upstream errors.

Response notes

- The service fetches matching child sitemaps from `/sitemap.xml` until `limit` URL entries is reached. - URL entries include `loc`, inferred `type`, `handle`, `lastmod`, `changefreq`, and optional `images`. - Blocked pages, malformed XML, and missing sitemap entries return upstream errors.