Cara Menggunakan API Pencarian AI Shoply

Ya. Anda dapat melakukan kueri ke Shoply AI Search secara terprogram dari backend Anda sendiri tanpa memuat widget di situs atau mengirim permintaan melalui storefront Shopify Anda.

API pencarian standar tersedia di setiap paket Shopify yang menyertakan AI Search, termasuk Forever Free. Permintaan API menggunakan alokasi pencarian bulanan yang sama dengan pencarian yang dilakukan melalui widget storefront. Lihat batas terbaru di halaman harga kami.

Jika Anda memerlukan batas yang lebih tinggi, perjanjian tingkat layanan, sumber data kustom, atau integrasi yang tidak menggunakan katalog Shopify yang diindeks oleh Shoply, hubungi kami tentang paket Enterprise.

Sebelum Memulai

Instal Shoply AI di toko Shopify yang katalognya ingin Anda cari dan biarkan pengindeksan produk awal selesai. Anda akan memerlukan domain myshopify.com permanen milik toko tersebut, seperti:

your-store.myshopify.com

API dapat dipanggil dari lingkungan backend mana pun. Kunci API terpisah tidak diperlukan untuk endpoint pencarian produk standar karena endpoint ini mengembalikan informasi katalog publik yang sama seperti yang dapat ditampilkan Shoply dalam pengalaman pencarian storefront.

Endpoint

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

Isi Permintaan

query adalah string JSON di dalam isi permintaan, bukan objek JSON bertingkat. Misalnya, frasa pencarian waterproof hiking boots dikirim sebagai:

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

Contoh cURL

Ganti your-store.myshopify.com dengan domain Shopify permanen toko Anda:

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
  }'

Contoh 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);

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

Respons

Permintaan yang berhasil akan mengembalikan:

{
  "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 adalah jumlah total produk yang cocok.
• docs berisi produk yang telah diperingkat untuk halaman yang diminta.
• display_filters berisi filter yang tersedia seperti harga, merek, warna, atau atribut lain yang spesifik untuk katalog.

Objek produk dapat berisi field tambahan tergantung pada katalog toko, varian, harga, dan konfigurasi Shoply. Klien sebaiknya menggunakan field yang diperlukan dan mengabaikan field yang tidak dikenal dengan aman.

Pagination

Gunakan start dan limit untuk meminta hasil tambahan. Misalnya, setelah meminta delapan produk dengan start: 0 dan limit: 8, minta halaman berikutnya dengan:

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

Berhentilah saat start + docs.length lebih besar dari atau sama dengan num_results, atau saat docs kosong.

Catatan Paket dan Integrasi

Jika storefront kustom Anda juga memerlukan percakapan, tambahkan chat ke storefront Shopify headless.

• Pencarian API standar bersifat self-service dan tidak memerlukan widget di situs.
• Toko Shopify Anda harus tetap terhubung ke Shoply AI agar indeks produknya tetap mutakhir.
• Pencarian API dan pencarian storefront berbagi alokasi pencarian bulanan untuk paket Shopify Anda.
• Simpan pemanggilan ini di backend Anda jika Anda ingin memusatkan caching, logging, retry, atau kontrol akses.
• Hubungi kami untuk dukungan Enterprise jika Anda memerlukan autentikasi kustom, throughput yang terjamin, SLA, katalog non-Shopify, atau batas di luar paket yang dipublikasikan.

Untuk bantuan memastikan store key Anda atau merencanakan integrasi produksi, hubungi Shoply AI.