Πώς να Ανεβάσετε τον Κατάλογό σας για το SiteChat

Αν χρησιμοποιείτε το SiteChat στον δικό σας ιστότοπο (όχι σε κατάστημα Shopify), μπορείτε να στείλετε δομημένες εγγραφές προϊόντων στη Shoply ώστε οι αγοραστές να μπορούν να τις βρίσκουν στη συνομιλία του SiteChat και στην αναζήτηση προϊόντων.

Αυτά τα endpoints χρησιμοποιούν το ίδιο Settings → Store owner API secret με το υπόλοιπο Shoply Merchant API, και η σελίδα Product Catalog του διαχειριστικού του SiteChat μπορεί να τα καλέσει με το access token του διαχειριστή σας όταν είστε συνδεδεμένοι. Τα καταστήματα Shopify συνεχίζουν να συγχρονίζουν τα δεδομένα καταλόγου μέσω του Shopify· αυτές οι διαδρομές μεταφόρτωσης είναι διαθέσιμες μόνο για λογαριασμούς SiteChat που δεν συγχρονίζουν ήδη κατάλογο Magento.

Στο διαχειριστικό του SiteChat, το Product Catalog ανοίγει μια περιοχή τύπου Shopify με Products, Collections και Inventory. Μπορείτε να προσθέσετε ή να επεξεργαστείτε προϊόντα, να εισαγάγετε CSV/Excel, να ομαδοποιήσετε προϊόντα σε χειροκίνητες συλλογές και να προσαρμόσετε τις ποσότητες αποθέματος.

Ποια API είναι Διαθέσιμα;

Οι επιτυχημένες αποθηκεύσεις προϊόντων ζητούν από τη Shoply να αναδημιουργήσει το ευρετήριο του καταστήματος. Μέχρι να ολοκληρωθεί αυτή η αναδημιουργία, οι αποκρίσεις αναφέρουν index_status: "pending". Τα δημοσιευμένα προϊόντα εμφανίζονται έπειτα τόσο στο ευρετήριο προϊόντων όσο και στη γνώση που χρησιμοποιεί η συνομιλία του SiteChat.

Ποιος Μπορεί να Χρησιμοποιήσει Αυτά τα API;

• Το κατάστημά σας πρέπει να είναι λογαριασμός SiteChat (app_platform is SiteChat).
• Τα κλειδιά καταστήματος Shopify (συμπεριλαμβανομένου οποιουδήποτε domain *.myshopify.com) απορρίπτονται.
• Η ταυτοποίηση πρέπει να χρησιμοποιεί είτε ένα έγκυρο store-owner API secret είτε ένα SiteChat admin access token για το ακριβές store_key του αιτήματος.
• Τα Shopify Admin API tokens δεν μπορούν να καλέσουν αυτές τις διαδρομές.

Δημιουργήστε ή ανανεώστε το owner secret με τον ίδιο τρόπο όπως και για άλλες ενσωματώσεις Merchant API: Πώς να Χρησιμοποιήσετε το Shoply Merchant API. Στην κονσόλα διαχείρισης του SiteChat, ανοίξτε το Product Catalog για να διαχειριστείτε προϊόντα, συλλογές και απόθεμα — ή να εισαγάγετε αρχείο CSV ή Excel — χωρίς να διαχειρίζεστε εσείς το secret.

Πώς Λειτουργεί η Ταυτοποίηση;

Από έναν server connector

Καλέστε το API από ένα αξιόπιστο backend μέσω HTTPS. Τοποθετήστε ένα JSON string στο header Authorization:

{
  "store_key": "YOUR_SITECHAT_STORE_KEY",
  "store_owner_api_secrete": "YOUR_STORE_OWNER_API_SECRET"
}

Το store_owner_api_secrete είναι το δημόσιο όνομα πεδίου, συμπεριλαμβανομένης της ιστορικής ορθογραφίας. Το store_owner_api_secret γίνεται επίσης αποδεκτό. Αυτό δεν είναι token Bearer.

Από το διαχειριστικό του SiteChat

Η σελίδα Product Catalog στέλνει αντ’ αυτού τη συνεδρία διαχειριστή στην οποία είστε συνδεδεμένοι:

{
  "store_key": "YOUR_SITECHAT_STORE_KEY",
  "admin_auth_token": "YOUR_SITECHAT_ACCESS_TOKEN"
}

Το access_token γίνεται αποδεκτό ως συνώνυμο του admin_auth_token.

Η παράμετρος ερωτήματος store_key πρέπει να ταιριάζει με το header. Διατηρείτε τα owner secrets μόνο σε server-side environment variables — ποτέ σε script βιτρίνας, URL ή δημόσιο αποθετήριο.

export SHOPLY_STORE_KEY="your-sitechat-store-key"
export SHOPLY_STORE_OWNER_API_SECRETE="shoply_owner_key_example123.secret-value"

Πώς Ανεβάζω Προϊόντα;

POST https://api.shoplyai.ai/merchant/products/batch?store_key=YOUR_SITECHAT_STORE_KEY

{
  "source": "woocommerce-main",
  "products": [
    {
      "external_id": "123",
      "title": "Trail shoes",
      "description": "Water-resistant hiking shoes.",
      "url": "https://example.com/products/trail-shoes",
      "currency": "USD",
      "price": "49.95",
      "original_price": "59.95",
      "available": true,
      "status": "published",
      "images": ["https://example.com/images/trail-shoes.jpg"],
      "categories": ["Footwear"],
      "metafields": {"material": "Leather"},
      "variants": [
        {
          "external_id": "124",
          "title": "Brown / 42",
          "sku": "TRAIL-BR-42",
          "price": "49.95",
          "available": true,
          "metafields": {"color": "Brown", "size": "42"}
        }
      ]
    }
  ]
}

Απαιτούμενα πεδία και κανόνες

• Απαιτούμενα πεδία προϊόντος: external_id, title, url, currency, price και available. Το status προεπιλέγεται σε published.
• Προαιρετικό απόθεμα: ορίστε tracks_inventory σε true και μια μη αρνητική quantity στο προϊόν ή την παραλλαγή. Η Shoply στη συνέχεια παράγει τη διαθεσιμότητα από το απόθεμα (quantity > 0) και αποθηκεύει το total_inventory για τις λίστες διαχείρισης.
• Το source ονομάζει τη σύνδεση καταλόγου (όχι απαραίτητα μια πλατφόρμα). Χρησιμοποιήστε ένα σταθερό όνομα όπως woocommerce-main. Επιτρεπόμενοι χαρακτήρες: πεζά γράμματα, αριθμοί, κάτω παύλες και ενωτικά· έως 64 χαρακτήρες. Τα προϊόντα που δημιουργούνται από φόρμα στο admin έχουν προεπιλεγμένο source το admin.
• Η ταυτότητα προϊόντος είναι ο συνδυασμός καταστήματος, source και external ID. Τα upserts των batch και single POST είναι πλήρεις αντικαταστάσεις, όχι patches: τα προαιρετικά πεδία που παραλείπονται διαγράφονται. Χρησιμοποιήστε PATCH για μερικές ενημερώσεις.
• Τα batch περιέχουν 1–50 προϊόντα και έως 2.000.000 bytes αιτήματος. Το επικυρωμένο JSON κάθε προϊόντος περιορίζεται σε 128.000 bytes, με έως 250 παραλλαγές.
• Προτιμήστε δεκαδικές συμβολοσειρές για τις τιμές. Το νόμισμα είναι κωδικός τριών κεφαλαίων γραμμάτων.
• Τα URL προϊόντων και εικόνων πρέπει να είναι HTTP(S). Η εισαγωγή δεν ανακτά αυτά τα URL για λογαριασμό σας.
• Χρησιμοποιήστε δημόσια metafields για αναζητήσιμα χαρακτηριστικά προϊόντων (το ανάλογο του SiteChat στα Shopify product metafields). Οι τιμές πρέπει να είναι απλές συμβολοσειρές. Το παλαιού τύπου attributes γίνεται αποδεκτό ως συνώνυμο. Το ιδιωτικό metadata προϊόντος δεν υποστηρίζεται πλέον.
• Τα προϊόντα draft και archived παραλείπονται από το επόμενο δημοσιευμένο ευρετήριο. Τα εξαντλημένα δημοσιευμένα προϊόντα παραμένουν ευρετηριασμένα με συνημμένη τη διαθεσιμότητα.
• Οι χειροκίνητες συλλογές αποθηκεύουν τίτλο, περιγραφή, κατάσταση και μια λίστα συμμετοχών προϊόντων (source + external_id). Οι έξυπνες/βασισμένες σε κανόνες συλλογές δεν υποστηρίζονται σε αυτή την έκδοση.

Δείγμα επιτυχούς απόκρισης

{
  "results": [
    {
      "external_id": "123",
      "product_id": "sitechat_product::woocommerce-main::<sha256-of-external-id>",
      "status": "stored"
    }
  ],
  "index_status": "pending",
  "index_revision": 1
}

Η Shoply επικυρώνει ολόκληρο το αίτημα πριν από την εγγραφή. Ένα HTTP 200 μπορεί παρ’ όλα αυτά να παραθέτει ορισμένα αποτελέσματα failed με error: "storage_error". Ελέγξτε κάθε αποτέλεσμα και επαναλάβετε τα αποτυχημένα προϊόντα. Αν το index_status είναι request_failed, η αποθήκευση πέτυχε αλλά ο προγραμματισμός της ευρετηρίασης δεν έγινε — επαναλάβετε επίσης τα αποθηκευμένα προϊόντα.

Παράδειγμα Python

import json
import os
import requests
 
store_key = os.environ["SHOPLY_STORE_KEY"]
headers = {
    "Authorization": json.dumps({
        "store_key": store_key,
        "store_owner_api_secrete": os.environ["SHOPLY_STORE_OWNER_API_SECRETE"],
    })
}
 
response = requests.post(
    "https://api.shoplyai.ai/merchant/products/batch",
    params={"store_key": store_key},
    headers=headers,
    json={
        "source": "custom",
        "products": [{
            "external_id": "123",
            "title": "Trail shoes",
            "url": "https://example.com/products/trail-shoes",
            "currency": "USD",
            "price": "49.95",
            "available": True,
        }],
    },
    timeout=60,
)
response.raise_for_status()
result = response.json()
failed = [item["external_id"] for item in result["results"] if item["status"] != "stored"]
if failed:
    raise RuntimeError(f"Products need retry: {failed}")
if result["index_status"] == "request_failed":
    raise RuntimeError("Products saved, but retry the batch to request indexing")

Πώς Επαληθεύω ένα Εισαγμένο Προϊόν;

GET https://api.shoplyai.ai/merchant/products?store_key=YOUR_SITECHAT_STORE_KEY&source=woocommerce-main&external_id=123

Χρησιμοποιήστε το ίδιο header Authorization. Η απόκριση περιλαμβάνει schema_version, updated_at, index_status και το κανονικοποιημένο product. Οι εγγραφές που λείπουν επιστρέφουν HTTP 404.

Αφού ο indexer υποβάθρου δημοσιεύσει μια αναδημιουργία, η κατάσταση ανάκτησης ανά προϊόν γίνεται indexed, excluded (για προϊόντα draft ή archived) ή limit_exceeded. Χρησιμοποιήστε GET /merchant/products/list για λίστα διαχείρισης. Αρχειοθετήστε λογικά με DELETE /merchant/products (ή ορίστε το status σε archived / draft) για να κρατήσετε ένα προϊόν εκτός του επόμενου δημοσιευμένου ευρετηρίου· δεν υπάρχει οριστική διαγραφή σε αυτή την έκδοση.

record = requests.get(
    "https://api.shoplyai.ai/merchant/products",
    params={
        "store_key": store_key,
        "source": "woocommerce-main",
        "external_id": "123",
    },
    headers=headers,
    timeout=30,
)
record.raise_for_status()
print(record.json()["index_status"], record.json()["product"]["title"])

Μπορώ να Ανεβάσω Εικόνες Προϊόντων;

Ναι. Αν μια εικόνα είναι ήδη διαθέσιμη σε μόνιμο δημόσιο HTTPS URL, τοποθετήστε αυτό το URL στη λίστα images του προϊόντος ή στο πεδίο image μιας παραλλαγής. Τα δημόσια S3 HTTPS URL λειτουργούν. Οι ακατέργαστες διαδρομές s3:// και τα signed URL μικρής διάρκειας δεν λειτουργούν.

Για να φιλοξενήσει η Shoply το αρχείο, ανεβάστε ακατέργαστα bytes εικόνας από το backend σας:

POST https://api.shoplyai.ai/merchant/products/images?store_key=YOUR_SITECHAT_STORE_KEY
Content-Type: image/png

Στείλτε τα ακατέργαστα bytes του αρχείου, όχι JSON, base64 ή multipart form data. Γίνονται αποδεκτά JPEG, PNG και WebP, έως 10 MiB και 20 εκατομμύρια pixels. Οι κινούμενες εικόνες δεν υποστηρίζονται. Η Shoply μετατρέπει την εικόνα σε WebP και αφαιρεί τα ενσωματωμένα μεταδεδομένα.

with open("trail-shoes.png", "rb") as image_file:
    response = requests.post(
        "https://api.shoplyai.ai/merchant/products/images",
        params={"store_key": store_key},
        headers={**headers, "Content-Type": "image/png"},
        data=image_file,
        timeout=60,
    )
response.raise_for_status()
image_url = response.json()["url"]

Το HTTP 201 επιστρέφει url, content_type, size_bytes, width και height. Η μεταφόρτωση μόνο μιας εικόνας δεν τη συνδέει με κάποιο προϊόν ούτε ζητά ευρετηρίαση. Συμπεριλάβετε το επιστρεφόμενο URL σε ένα πλήρες προϊόν και υποβάλετέ το ξανά μέσω του /merchant/products/batch.

Η ίδια εικόνα που ανεβαίνει ξανά για τον ίδιο λογαριασμό επαναχρησιμοποιεί το URL της. Μια τροποποιημένη εικόνα λαμβάνει νέο URL. Δεν υπάρχει endpoint διαγραφής εικόνας σε αυτή την έκδοση.

Πότε Εμφανίζονται τα Προϊόντα στη Συνομιλία και την Αναζήτηση;

Μετά από μια επιτυχημένη αποθήκευση batch, η Shoply ζητά αναδημιουργία ευρετηρίου στο παρασκήνιο. Οι αποκρίσεις αναφέρουν index_status: "pending" μέχρι ο worker να δημοσιεύσει το νέο ευρετήριο. Δεν υπάρχει σταθερή εγγύηση χρόνου ολοκλήρωσης.

• Τα δημοσιευμένα προϊόντα εισέρχονται τόσο στην αναζήτηση προϊόντων όσο και στη γνώση που χρησιμοποιεί η συνομιλία του SiteChat.
• Τα draft και archived προϊόντα εξαιρούνται στην επόμενη αναδημιουργία.
• Αν η ευρετηρίαση δεν προγραμματίστηκε (index_status: "request_failed"), επαναλάβετε το batch για τα προϊόντα που έχουν ήδη αποθηκευτεί επιτυχώς.

Ποια Σφάλματα Πρέπει να Περιμένω;

Τα secrets λήγουν μετά από 90 ημέρες. Δημιουργήστε αντικατάσταση στο Settings → Store owner API secret πριν από τη λήξη και ανακαλέστε κάθε secret που δεν χρειάζεστε πλέον. Το ίδιο secret μπορεί επίσης να καλέσει endpoints analytics, conversation και knowledge που τεκμηριώνονται στον οδηγό Merchant API.

Για βοήθεια με μια ενσωμάτωση, επικοινωνήστε με το Shoply AI.