Как использовать API поиска Shoply AI

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

Стандартный API поиска доступен в каждом плане Shopify, который включает AI Search, включая Forever Free. API-запросы используют тот же ежемесячный лимит поисков, что и запросы, выполняемые через виджет витрины. Актуальные лимиты смотрите на нашей странице цен.

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

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

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

your-store.myshopify.com

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

Endpoint

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 будет пустым.

Примечания по планам и интеграции

Если вашей кастомной витрине также нужен разговорный интерфейс, добавьте чат в headless-витрину Shopify.

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

Если вам нужна помощь с подтверждением store key вашего магазина или планированием production-интеграции, свяжитесь с Shoply AI.