Cum să folosești API-ul Shoply AI Search

Da. Poți interoga programatic Shoply AI Search din propriul backend fără a încărca widgetul de pe site și fără a trimite cererea prin storefront-ul tău Shopify.

API-ul standard de căutare este disponibil cu orice plan Shopify care include AI Search, inclusiv Forever Free. Cererile API folosesc aceeași alocare lunară de căutări ca și căutările efectuate prin widgetul din storefront. Vezi limitele actuale pe pagina noastră de prețuri.

Dacă ai nevoie de limite mai mari, de un acord privind nivelul serviciului, de o sursă de date personalizată sau de o integrare care nu folosește un catalog Shopify indexat de Shoply, contactează-ne pentru un plan Enterprise.

Înainte să începi

Instalează Shoply AI în magazinul Shopify al cărui catalog vrei să îl cauți și așteaptă finalizarea indexării inițiale a produselor. Vei avea nevoie de domeniul permanent myshopify.com al magazinului, cum ar fi:

your-store.myshopify.com

API-ul poate fi apelat din orice mediu backend. Nu este necesară o cheie API separată pentru endpointul standard de căutare a produselor, deoarece acesta returnează aceleași informații publice din catalog pe care Shoply le poate afișa în experiența de căutare din storefront.

Endpoint

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

Corpul cererii

query este un șir JSON în interiorul corpului cererii, nu un obiect JSON imbricat. De exemplu, expresia de căutare waterproof hiking boots este trimisă astfel:

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

Exemplu cURL

Înlocuiește your-store.myshopify.com cu domeniul Shopify permanent al magazinului tău:

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

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

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

Răspuns

O cerere reușită returnează:

{
  "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 este numărul total de produse care corespund.
• docs conține produsele ordonate după relevanță pentru pagina solicitată.
• display_filters conține filtrele disponibile, cum ar fi prețul, brandul, culoarea sau alte atribute specifice catalogului.

Obiectele de produs pot conține câmpuri suplimentare în funcție de catalogul magazinului, variante, prețuri și configurația Shoply. Clienții ar trebui să folosească câmpurile de care au nevoie și să ignore în siguranță câmpurile necunoscute.

Paginare

Folosește start și limit pentru a solicita rezultate suplimentare. De exemplu, după ce soliciți opt produse cu start: 0 și limit: 8, solicită pagina următoare cu:

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

Oprește-te când start + docs.length este mai mare sau egal cu num_results sau când docs este gol.

Note despre plan și integrare

Dacă storefront-ul tău personalizat are nevoie și de conversație, adaugă chat unui storefront Shopify headless.

• Căutarea API standard este self-service și nu necesită widgetul de pe site.
• Magazinul tău Shopify trebuie să rămână conectat la Shoply AI pentru ca indexul său de produse să rămână actualizat.
• Căutările prin API și căutările din storefront folosesc în comun alocarea lunară de căutări pentru planul tău Shopify.
• Păstrează apelul în backend dacă vrei să centralizezi cache-ul, jurnalizarea, reîncercările sau controlul accesului.
• Contactează-ne pentru suport Enterprise dacă ai nevoie de autentificare personalizată, throughput garantat, un SLA, un catalog non-Shopify sau limite peste planurile publicate.

Pentru ajutor în confirmarea cheii magazinului tău sau în planificarea unei integrări de producție, contactează Shoply AI.