Как получить доступ к Shoply AI Search через API

Да. Вы можете программно отправлять запросы к Shoply AI Search из собственного бэкенда, не загружая виджет на сайте и не отправляя запрос через витрину Shopify.

Стандартный Search API доступен с любым тарифом Shopify, включающим AI Search, в том числе с Forever Free. Запросы к API используют тот же ежемесячный лимит поисковых запросов, что и поиск через виджет на витрине. Текущие ограничения см. на нашей странице с тарифами.

Если вам нужны более высокие лимиты, соглашение об уровне обслуживания, пользовательский источник данных или интеграция, не использующая каталог Shopify, проиндексированный Shoply, свяжитесь с нами по поводу тарифа Enterprise.

Перед началом

Установите Shoply AI в магазине Shopify, каталог которого вы хотите искать, и дождитесь завершения первоначальной индексации товаров. Вам понадобится постоянный домен магазина myshopify.com, например:

your-store.myshopify.com

API можно вызывать из любой среды бэкенда. Отдельный ключ API для стандартной конечной точки поиска товаров не требуется, поскольку она возвращает ту же общедоступную информацию о каталоге, которую Shoply может отображать в интерфейсе поиска на витрине.

Конечная точка

POST https://api.shoplyai.ai/product_query_v2
Content-Type: application/json

Тело запроса

query — это строка JSON внутри тела запроса, а не вложенный объект JSON. Например, поисковая фраза waterproof hiking boots отправляется так:

"{\"keywords\":\"waterproof hiking boots\"}"

Пример cURL

Замените your-store.myshopify.com на постоянный домен Shopify вашего магазина:

curl --request POST "https://api.shoplyai.ai/product_query_v2" \
  --header "Content-Type: application/json" \
  --data '{
    "store_key": "your-store.myshopify.com",
    "query": "{\"keywords\":\"waterproof hiking boots\"}",
    "start": 0,
    "limit": 8
  }'

Пример на JavaScript

// Build the inner query separately because the API expects it as a JSON-encoded string.
const searchQuery = JSON.stringify({
  keywords: "waterproof hiking boots"
});
 
const response = await fetch("https://api.shoplyai.ai/product_query_v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    store_key: "your-store.myshopify.com",
    query: searchQuery,
    start: 0,
    limit: 8
  })
});
 
if (!response.ok) {
  throw new Error(`Shoply search failed with status ${response.status}`);
}
 
const results = await response.json();
console.log(results.docs);

Пример на Python

import json
import requests
 
# The query value is encoded separately to match Shoply's structured search contract.
payload = {
    "store_key": "your-store.myshopify.com",
    "query": json.dumps({"keywords": "waterproof hiking boots"}),
    "start": 0,
    "limit": 8,
}
 
response = requests.post(
    "https://api.shoplyai.ai/product_query_v2",
    json=payload,
    timeout=30,
)
response.raise_for_status()
 
results = response.json()
print(results["docs"])

Ответ

Успешный запрос возвращает:

{
  "num_results": 2,
  "docs": [
    {
      "product_id": "gid://shopify/Product/1234567890",
      "url": "https://your-store.example/products/example-product",
      "product_name": "Example Product",
      "brand": "Example Brand",
      "current_price": "129.00",
      "currency": "USD",
      "main_image": "https://cdn.shopify.com/example-product.jpg",
      "selected_variant_id": "gid://shopify/ProductVariant/1234567891"
    }
  ],
  "display_filters": []
}

• num_results — общее количество соответствующих товаров.
• docs содержит товары, отсортированные по релевантности для запрошенной страницы.
• display_filters содержит доступные фильтры, например по цене, бренду, цвету и другим атрибутам конкретного каталога.

Объекты товаров могут содержать дополнительные поля в зависимости от каталога магазина, вариантов, цен и конфигурации Shoply. Клиентам следует использовать нужные им поля и безопасно игнорировать незнакомые поля.

Постраничная навигация

Используйте start и limit, чтобы запрашивать дополнительные результаты. Например, после запроса восьми товаров с start: 0 и limit: 8 запросите следующую страницу:

{
  "start": 8,
  "limit": 8
}

Остановитесь, когда start + docs.length станет больше или равно num_results, либо когда docs окажется пустым.

Примечания о тарифах и интеграции

• Стандартный поиск через API доступен самостоятельно и не требует виджета на сайте.
• Ваш магазин Shopify должен оставаться подключённым к Shoply AI, чтобы индекс товаров мог поддерживаться в актуальном состоянии.
• Поиск через API и поиск на витрине используют общий ежемесячный лимит поисковых запросов вашего тарифа Shopify.
• Оставляйте вызов на своём бэкенде, если хотите централизовать кэширование, ведение журналов, повторы запросов или контроль доступа.
• Обратитесь в службу поддержки Enterprise, если вам нужны пользовательская аутентификация, гарантированная пропускная способность, SLA, каталог не на Shopify или лимиты выше опубликованных тарифов.

Если вам нужна помощь с подтверждением ключа магазина или планированием интеграции для рабочей среды, свяжитесь с Shoply AI.