> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.ehunt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 商品查询接口

### **Shopify 商品数据查询**

该接口用于**VIP 用户查询 Shopify 商品数据**，支持多维度筛选（销量、价格、广告数、竞争度等）、排序与分页。

|  **项目**  | **说明**     |
| :------: | :--------- |
| **接口类型** | REST API   |
| **请求方式** | POST       |
| **数据格式** | JSON       |
| **鉴权方式** | API Key    |
| **适用用户** | VIP / 订阅用户 |

**接口地址**

text

```text theme={null}
POST /api/vi/shopify-items
```

**鉴权说明**

请求需在 Header 中携带 API Key：

text

```text theme={null}
X-VIP-TOKEN: your_api_key_here
```

若 API Key 无效、过期或无订阅权限，将返回错误响应。

**请求参数**

|         **参数名**        | **类型** | **必填** | **说明**                                                                                                                                                                          |
| :--------------------: | :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|       search\_key      | string | 否      | 搜索关键词或Shopify商品/店铺URL                                                                                                                                                           |
|        sort\_by        | int    | 否      | 排序字段：14=周销量降序(默认)，1=上架时间降序，2=上架时间升序，3=价格降序，4=价格升序，7=周销量降序，9=广告数降序，10=广告数升序，11=竞争度降序，12=竞争度升序，13=创建时间降序，15=周销量升序，16=周销售额降序，17=周销售额升序，18=周销售额增长率降序，19=周销售额增长率升序，20=相关度升序，21=相关度降序 |
|        page\_num       | int    | 否      | 页码，从1开始                                                                                                                                                                         |
|       page\_size       | int    | 否      | 每页数量，最大100                                                                                                                                                                      |
|       price\_min       | float  | 否      | 最低价格(USD)                                                                                                                                                                       |
|       price\_max       | float  | 否      | 最高价格(USD)                                                                                                                                                                       |
|   sales\_weekly\_min   | int    | 否      | 周销量最小值                                                                                                                                                                          |
|   sales\_weekly\_max   | int    | 否      | 周销量最大值                                                                                                                                                                          |
| published\_time\_begin | string | 否      | 上架开始日期 YYYY-MM-DD                                                                                                                                                               |
|  published\_time\_end  | string | 否      | 上架结束日期 YYYY-MM-DD                                                                                                                                                               |
|      facebook\_ad      | int    | 否      | 是否有Facebook广告：1=有                                                                                                                                                               |
|    competition\_min    | int    | 否      | 竞争度最小值（店铺数量）                                                                                                                                                                    |
|    competition\_max    | int    | 否      | 竞争度最大值                                                                                                                                                                          |
|      has\_supplier     | int    | 否      | 是否有货源：1=有，0=无                                                                                                                                                                   |
|      show\_deleted     | int    | 否      | 是否显示已下架商品：1=是，0=否                                                                                                                                                               |
|         country        | string | 否      | 发货国家，两位国家代码（如US、CN）                                                                                                                                                             |
|          lang          | string | 否      | 语言：en/cn，默认en                                                                                                                                                                   |

**请求示例**

python

```json theme={null}
import requests
import json

url = "https://api.ehunt.ai/api/vi/shopify-items"
headers = {
    "Content-Type": "application/json",
    "X-VIP-TOKEN": "your_api_key_here"
}
payload = {
    "search_key": "dress",
    "price_min": 10,
    "price_max": 50,
    "sales_weekly_min": 10,
    "sort_by": 7,
    "page_num": 1,
    "page_size": 20
}
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=2))
```

**返回示例**

json

```json theme={null}
{
  "code": 200,
  "message": "OK",
  "data": {
    "product_num": 100,
    "page_size": 20,
    "final_count": 20,
    "list": [
      {
        "product_id": "12345",
        "title": "Vintage Cotton Dress",
        "product_link": "https://example.myshopify.com/products/vintage-dress",
        "preview_image_url": "https://cdn.shopify.com/.../image.jpg",
        "country": "US",
        "min_price": 29.99,
        "max_price": 49.99,
        "store_id": "store_123",
        "shop_id": "shop_123",
        "store_link": "example.myshopify.com",
        "store_rank": "A",
        "competitor_count": 15,
        "facebook_ad_count": 3,
        "week_order_count": "1,234",
        "week_revenue_count": "12,345",
        "week_revenue_growth": 15.5,
        "shelf_time": "2024-01-15",
        "is_deleted": 0,
        "is_favourite": 0
      }
    ]
  },
  "used_today": 150,
  "remaining_today": 350
}
```

**响应字段说明**

|        **字段名**        | **类型** | **说明**          |
| :-------------------: | :----- | :-------------- |
|      product\_id      | string | 商品ID            |
|         title         | string | 商品标题            |
|     product\_link     | string | 商品链接            |
|  preview\_image\_url  | string | 商品主图URL         |
|        country        | string | 发货国家            |
|       min\_price      | float  | 最低价格(USD)       |
|       max\_price      | float  | 最高价格(USD)       |
|       store\_id       | string | 店铺ID            |
|        shop\_id       | string | 商店ID            |
|      store\_link      | string | 店铺链接            |
|      store\_rank      | string | 店铺等级            |
|   competitor\_count   | int    | 竞争度（店铺数量）       |
|  facebook\_ad\_count  | int    | Facebook广告数量    |
|   week\_order\_count  | string | 周销量（格式化）        |
|  week\_revenue\_count | string | 周销售额            |
| week\_revenue\_growth | float  | 周销售额增长率(%)      |
|      shelf\_time      | string | 上架时间            |
|      is\_deleted      | int    | 是否下架（0=上架，1=下架） |
|     is\_favourite     | int    | 是否收藏            |

## **API 返回码说明**

| **Code** | **说明**              |
| :------: | :------------------ |
|    200   | 成功                  |
|    401   | 认证失败（API Key 无效或过期） |
|    402   | 积分不足或订阅过期           |
|    403   | 无访问权限               |
|    429   | 请求频率过高，触发限流         |
|    500   | 服务器内部错误             |

***

## **积分说明**

按实际返回数据量计费，**每条数据消耗 1 个积分**，清晰透明的消费机制。

* 商品查询：每条返回的商品消耗 1 积分
* 店铺查询：每条返回的店铺消耗 1 积分
* 每日积分上限与订阅套餐有关， Etsy、Shopify、Temu 全部 VIP 接口共用每日积分