Πώς να χρησιμοποιήσετε το Shoply AI Search API

Ναι. Μπορείτε να κάνετε ερωτήματα στο Shoply AI Search μέσω προγραμματισμού από το δικό σας backend χωρίς να φορτώσετε το widget του ιστότοπου ή να στείλετε το αίτημα μέσω του Shopify storefront σας.

Το τυπικό search API είναι διαθέσιμο σε κάθε πρόγραμμα Shopify που περιλαμβάνει AI Search, συμπεριλαμβανομένου του Forever Free. Τα API requests χρησιμοποιούν το ίδιο μηνιαίο όριο αναζητήσεων με τις αναζητήσεις που γίνονται μέσω του storefront widget. Δείτε τα τρέχοντα όρια στη σελίδα τιμολόγησής μας.

Αν χρειάζεστε υψηλότερα όρια, συμφωνία επιπέδου υπηρεσίας, προσαρμοσμένη πηγή δεδομένων ή ενσωμάτωση που δεν χρησιμοποιεί κατάλογο Shopify με ευρετηρίαση από το Shoply, επικοινωνήστε μαζί μας για ένα πρόγραμμα Enterprise.

Πριν ξεκινήσετε

Εγκαταστήστε το Shoply AI στο κατάστημα Shopify του οποίου τον κατάλογο θέλετε να αναζητήσετε και περιμένετε να ολοκληρωθεί η αρχική ευρετηρίαση προϊόντων. Θα χρειαστείτε το μόνιμο domain myshopify.com του καταστήματος, όπως:

your-store.myshopify.com

Το API μπορεί να κληθεί από οποιοδήποτε backend περιβάλλον. Δεν απαιτείται ξεχωριστό API key για το τυπικό 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 domain του καταστήματός σας:

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 περιέχει διαθέσιμα φίλτρα όπως τιμή, brand, χρώμα ή άλλα χαρακτηριστικά ειδικά για τον κατάλογο.

Τα αντικείμενα προϊόντων μπορεί να περιέχουν επιπλέον πεδία ανάλογα με τον κατάλογο του καταστήματος, τις παραλλαγές, την τιμολόγηση και τη διαμόρφωση του Shoply. Οι clients θα πρέπει να χρησιμοποιούν τα πεδία που χρειάζονται και να αγνοούν με ασφάλεια όσα πεδία δεν αναγνωρίζουν.

Σελιδοποίηση

Χρησιμοποιήστε τα start και limit για να ζητήσετε επιπλέον αποτελέσματα. Για παράδειγμα, αφού ζητήσετε οκτώ προϊόντα με start: 0 και limit: 8, ζητήστε την επόμενη σελίδα με:

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

Σταματήστε όταν το start + docs.length είναι μεγαλύτερο ή ίσο με το num_results, ή όταν το docs είναι κενό.

Σημειώσεις για προγράμματα και ενσωμάτωση

Αν το προσαρμοσμένο storefront σας χρειάζεται επίσης συνομιλία, προσθέστε chat σε ένα headless Shopify storefront.

• Η τυπική αναζήτηση API είναι self-service και δεν απαιτεί το on-site widget.
• Το κατάστημά σας στο Shopify πρέπει να παραμένει συνδεδεμένο με το Shoply AI ώστε το ευρετήριο προϊόντων του να παραμένει ενημερωμένο.
• Οι αναζητήσεις μέσω API και οι αναζητήσεις στο storefront μοιράζονται το μηνιαίο όριο αναζητήσεων του προγράμματος Shopify σας.
• Διατηρήστε την κλήση στο backend σας αν θέλετε να συγκεντρώσετε caching, logging, retries ή έλεγχο πρόσβασης.
• Επικοινωνήστε μαζί μας για υποστήριξη Enterprise αν χρειάζεστε προσαρμοσμένο authentication, εγγυημένο throughput, SLA, κατάλογο εκτός Shopify ή όρια πέρα από τα δημοσιευμένα προγράμματα.

Για βοήθεια στην επιβεβαίωση του store key σας ή στον σχεδιασμό μιας production ενσωμάτωσης, επικοινωνήστε με το Shoply AI.