Shoply AI Search API Nasıl Kullanılır

Evet. Shoply AI Search’ü, site içi widget’ı yüklemeden veya isteği Shopify vitrininiz üzerinden göndermeden, kendi backend’inizden programlı olarak sorgulayabilirsiniz.

Standart arama API’si, Forever Free dahil olmak üzere AI Search içeren her Shopify planında kullanılabilir. API istekleri, vitrin widget’ı üzerinden yapılan aramalarla aynı aylık arama hakkını kullanır. Güncel limitleri fiyatlandırma sayfamızda görebilirsiniz.

Daha yüksek limitlere, bir hizmet seviyesi sözleşmesine, özel bir veri kaynağına veya Shoply tarafından indekslenen bir Shopify kataloğunu kullanmayan bir entegrasyona ihtiyacınız varsa, Enterprise planı hakkında bizimle iletişime geçin.

Başlamadan Önce

Aramak istediğiniz kataloğa sahip Shopify mağazasına Shoply AI’ı yükleyin ve ilk ürün indekslemesinin tamamlanmasını bekleyin. Mağazanın kalıcı myshopify.com alan adına ihtiyacınız olacak, örneğin:

your-store.myshopify.com

API, herhangi bir backend ortamından çağrılabilir. Ayrı bir API anahtarı, standart ürün arama uç noktası için gerekli değildir; çünkü bu uç nokta, Shoply’nin vitrin arama deneyiminde gösterebildiği aynı herkese açık katalog bilgilerini döndürür.

Uç Nokta

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

İstek Gövdesi

query, istek gövdesi içinde yer alan bir JSON dizesidir; iç içe geçmiş bir JSON nesnesi değildir. Örneğin, waterproof hiking boots arama ifadesi şu şekilde gönderilir:

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

cURL Örneği

your-store.myshopify.com ifadesini mağazanızın kalıcı Shopify alan adıyla değiştirin:

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 Örneği

// 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 Örneği

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"])

Yanıt

Başarılı bir istek şunu döndürür:

{
  "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, eşleşen ürünlerin toplam sayısıdır.
• docs, istenen sayfa için sıralanmış ürünleri içerir.
• display_filters, fiyat, marka, renk veya kataloğa özgü diğer nitelikler gibi kullanılabilir filtreleri içerir.

Ürün nesneleri, mağazanın kataloğuna, varyantlarına, fiyatlandırmasına ve Shoply yapılandırmasına bağlı olarak ek alanlar içerebilir. İstemciler ihtiyaç duydukları alanları kullanmalı ve tanımadıkları alanları güvenle yok saymalıdır.

Sayfalama

Ek sonuçlar istemek için start ve limit kullanın. Örneğin, start: 0 ve limit: 8 ile sekiz ürün istedikten sonra, sonraki sayfayı şu şekilde isteyin:

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

start + docs.length, num_results değerine eşit veya ondan büyük olduğunda ya da docs boş olduğunda durun.

Plan ve Entegrasyon Notları

Özel vitrininizin ayrıca konuşma özelliğine de ihtiyacı varsa, headless bir Shopify vitrininize chat ekleyin.

• Standart API araması self-service’tir ve site içi widget gerektirmez.
• Ürün indeksinin güncel kalabilmesi için Shopify mağazanız Shoply AI’a bağlı kalmalıdır.
• API aramaları ve vitrin aramaları, Shopify planınız için aynı aylık arama hakkını paylaşır.
• Önbellekleme, günlükleme, yeniden denemeler veya erişim kontrolünü merkezileştirmek istiyorsanız çağrıyı backend’inizde tutun.
• Özel kimlik doğrulama, garantili aktarım kapasitesi, bir SLA, Shopify dışı bir katalog veya yayınlanan planların ötesinde limitlere ihtiyacınız varsa Enterprise desteği için bizimle iletişime geçin.

Mağaza anahtarınızı doğrulama veya üretim entegrasyonu planlama konusunda yardım için Shoply AI ile iletişime geçin.