כיצד להעלות את הקטלוג שלך עבור SiteChat

אם אתם משתמשים ב-SiteChat באתר שלכם (ולא בחנות Shopify), תוכלו לשלוח רשומות מוצרים מובְנות ל-Shoply כדי שקונים יוכלו למצוא אותן בצ’אט של SiteChat ובחיפוש מוצרים.

נקודות הקצה האלה משתמשות באותו Settings → Store owner API secret כמו שאר Shoply Merchant API, ועמוד Product Catalog בניהול SiteChat יכול לקרוא להן עם אסימון הגישה של האדמין כאשר אתם מחוברים. חנויות Shopify ממשיכות לסנכרן נתוני קטלוג דרך Shopify; מסלולי ההעלאה האלה זמינים רק עבור חשבונות SiteChat שאינם מסנכרנים כבר קטלוג Magento.

בניהול SiteChat, Product Catalog פותח אזור בסגנון Shopify עם Products, Collections ו-Inventory. תוכלו להוסיף או לערוך מוצרים, לייבא CSV/Excel, לקבץ מוצרים לאוספים ידניים ולהתאים כמויות מלאי.

אילו APIs זמינים?

שמירות מוצרים מוצלחות מבקשות מ-Shoply לבנות מחדש את אינדקס החנות. עד שהבנייה מחדש מסתיימת, התגובות ידווחו על index_status: "pending". לאחר מכן, מוצרים שפורסמו יופיעו גם באינדקס המוצרים וגם בידע שבו משתמש הצ’אט של SiteChat.

מי יכול להשתמש ב-APIs האלה?

• החנות שלכם חייבת להיות חשבון SiteChat (app_platform הוא SiteChat).
• מפתחות של חנויות Shopify (כולל כל דומיין *.myshopify.com) יידחו.
• האימות חייב להשתמש או בסוד API תקף של בעל החנות או באסימון גישה של אדמין SiteChat עבור ה-store_key המדויק שבבקשה.
• אסימוני Shopify Admin API לא יכולים לקרוא למסלולים האלה.

צרו או החליפו את סוד הבעלים באותו אופן כמו באינטגרציות אחרות של Merchant API: How to Use the Shoply Merchant API. בקונסולת הניהול של SiteChat, פתחו את Product Catalog כדי לנהל מוצרים, אוספים ומלאי — או לייבא קובץ CSV או Excel — בלי לנהל את הסוד בעצמכם.

כיצד פועל האימות?

מתוך מחבר שרת

קראו ל-API מ-backend מהימן דרך HTTPS. שימו מחרוזת JSON בכותרת Authorization:

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

store_owner_api_secrete הוא שם השדה הציבורי, כולל האיות ההיסטורי. גם store_owner_api_secret מתקבל. זה אינו אסימון Bearer.

מתוך ניהול SiteChat

עמוד Product Catalog שולח במקום זאת את סשן האדמין המחובר שלכם:

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

access_token מתקבל ככינוי חלופי ל-admin_auth_token.

פרמטר השאילתה store_key חייב להתאים לכותרת. שמרו סודות בעלים רק במשתני סביבה בצד השרת — לעולם לא בסקריפט storefront, ב-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 תווים. מוצרים שנוצרים מטופס בניהול מקבלים כברירת מחדל source בשם admin.
• זהות המוצר היא השילוב של store, source ו-external ID. פעולות upsert של POST יחיד ואצווה הן החלפות מלאות, לא patches: שדות אופציונליים שהושמטו ינוקו. השתמשו ב-PATCH לעדכונים חלקיים.
• אצוות מכילות 1–50 מוצרים ולכל היותר 2,000,000 בייטים לבקשה. ה-JSON המאומת של כל מוצר מוגבל ל-128,000 בייטים, עם עד 250 וריאנטים.
• העדיפו מחרוזות עשרוניות למחירים. המטבע הוא קוד בן שלוש אותיות גדולות באנגלית.
• כתובות URL של מוצרים ותמונות חייבות להיות HTTP(S). הייבוא לא מושך עבורכם את ה-URLs האלה.
• השתמשו ב-metafields ציבוריים עבור מפרטי מוצר הניתנים לחיפוש (המקבילה של SiteChat ל-metafields של מוצרי Shopify). הערכים חייבים להיות מחרוזות פשוטות. גם 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

השתמשו באותה כותרת Authorization. התגובה כוללת את schema_version, updated_at, index_status ואת ה-product המנורמל. רשומות חסרות מחזירות HTTP 404.

לאחר שהאינדקסר ברקע מפרסם בנייה מחדש, סטטוס הקריאה החוזרת לכל מוצר הופך ל-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"])

האם אפשר להעלות תמונות מוצר?

כן. אם תמונה כבר זמינה ב-URL ציבורי קבוע של HTTPS, שימו את ה-URL הזה ברשימת images של המוצר או בשדה image של וריאנט. כתובות URL ציבוריות של S3 ב-HTTPS עובדות. נתיבי s3:// גולמיים ו-URLs חתומים קצרי-חיים אינם עובדים.

כדי ש-Shoply תארח את הקובץ, העלו בייטים גולמיים של התמונה מה-backend שלכם:

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

שלחו את בייטי הקובץ הגולמיים, לא JSON, לא base64 ולא multipart form data. פורמטים JPEG, PNG ו-WebP מתקבלים, עד 10 MiB ועד 20 מיליון פיקסלים. תמונות מונפשות אינן נתמכות. Shoply ממירה את התמונה ל-WebP ומסירה metadata מוטמע.

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 חדש. אין נקודת קצה למחיקת תמונות בגרסה זו.

מתי המוצרים מופיעים בצ’אט ובחיפוש?

לאחר שמירת אצווה מוצלחת, Shoply מבקשת בנייה מחדש של אינדקס ברקע. התגובות מדווחות index_status: "pending" עד שה-worker מפרסם את האינדקס החדש. אין התחייבות לזמן סיום קבוע.

• מוצרים שפורסמו נכנסים גם לחיפוש המוצרים וגם לידע שבו משתמש הצ’אט של SiteChat.
• מוצרים במצב Draft ו-Archived מוחרגים בבנייה מחדש הבאה.
• אם האינדוקס לא תוזמן (index_status: "request_failed"), נסו שוב את האצווה עבור המוצרים שכבר נשמרו בהצלחה.

לאילו שגיאות כדאי לצפות?

תוקף הסודות פג לאחר 90 ימים. צרו סוד חלופי ב-Settings → Store owner API secret לפני הפקיעה, ובטלו כל סוד שאינכם זקוקים לו עוד. אותו סוד יכול גם לקרוא לנקודות קצה של אנליטיקה, שיחות וידע המתועדות ב-Merchant API guide.

לעזרה עם אינטגרציה, צרו קשר עם Shoply AI.