Как да използвате Shoply AI Search API

Да. Можете програмно да заявявате Shoply AI Search от собствения си бекенд, без да зареждате уиджета на сайта или да изпращате заявката през вашия Shopify storefront.

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

Ако имате нужда от по-високи лимити, споразумение за ниво на услугата, персонализиран източник на данни или интеграция, която не използва Shopify каталог, индексиран от Shoply, свържете се с нас относно Enterprise план.

Преди да започнете

Инсталирайте Shoply AI в Shopify магазина, чийто каталог искате да търсите, и изчакайте първоначалното индексиране на продуктите да завърши. Ще ви е нужен постоянният myshopify.com домейн на магазина, например:

your-store.myshopify.com

API може да бъде извиквано от всяка бекенд среда. Не е необходим отделен API ключ за стандартния endpoint за търсене на продукти, защото той връща същата публична информация за каталога, която Shoply може да показва в storefront търсенето.

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 е празно.

Бележки за плановете и интеграцията

Ако вашият custom storefront също се нуждае от разговорни възможности, добавете чат към headless Shopify storefront.

• Стандартното API търсене е self-service и не изисква уиджета на сайта.
• Вашият Shopify магазин трябва да остане свързан с Shoply AI, за да може продуктовият му индекс да се поддържа актуален.
• API търсенията и storefront търсенията споделят месечния лимит за търсения на вашия Shopify план.
• Дръжте извикването в бекенда си, ако искате да централизирате кеширане, логване, повторни опити или контрол на достъпа.
• Свържете се с нас за Enterprise поддръжка, ако имате нужда от персонализирана автентикация, гарантиран throughput, SLA, каталог извън Shopify или лимити над публикуваните планове.

За помощ при потвърждаване на ключа на магазина ви или планиране на продукционна интеграция, свържете се с Shoply AI.