SiteChat के लिए अपनी कैटलॉग कैसे अपलोड करें

यदि आप अपनी स्वयं की वेबसाइट पर SiteChat का उपयोग करते हैं (Shopify स्टोर पर नहीं), तो आप Shoply को संरचित उत्पाद रिकॉर्ड भेज सकते हैं ताकि खरीदार उन्हें SiteChat चैट और उत्पाद खोज में ढूंढ सकें।

ये endpoints बाकी Shoply Merchant API की तरह ही वही Settings → Store owner API secret उपयोग करते हैं, और SiteChat admin का Product Catalog पेज आपके signed-in admin access token के साथ इन्हें कॉल कर सकता है। Shopify स्टोर Shopify के माध्यम से कैटलॉग डेटा सिंक करते रहते हैं; ये upload routes केवल उन SiteChat accounts के लिए उपलब्ध हैं जो पहले से Magento कैटलॉग सिंक नहीं करते।

SiteChat admin में, Product Catalog एक Shopify-style क्षेत्र खोलता है जिसमें Products, Collections, और Inventory होते हैं। आप उत्पाद जोड़ या संपादित कर सकते हैं, CSV/Excel import कर सकते हैं, उत्पादों को manual collections में समूहित कर सकते हैं, और stock quantities समायोजित कर सकते हैं।

कौन-कौन से APIs उपलब्ध हैं?

सफल product saves पर Shoply store index को rebuild करने का अनुरोध करता है। जब तक वह rebuild पूरा नहीं होता, responses index_status: "pending" रिपोर्ट करती हैं। उसके बाद published products, product index और SiteChat chat द्वारा उपयोग किए जाने वाले knowledge—दोनों में दिखाई देते हैं।

इन APIs का उपयोग कौन कर सकता है?

• आपका स्टोर एक SiteChat account होना चाहिए (app_platform SiteChat है)।
• Shopify store keys (किसी भी *.myshopify.com domain सहित) अस्वीकार कर दिए जाते हैं।
• Authentication में या तो एक मान्य store-owner API secret होना चाहिए या अनुरोध में दिए गए सटीक store_key के लिए SiteChat admin access token।
• Shopify Admin API tokens इन routes को कॉल नहीं कर सकते।

Owner secret बनाएं या rotate करें उसी तरह जैसे अन्य Merchant API integrations के लिए: How to Use the Shoply Merchant API. SiteChat admin console में, Product Catalog खोलें ताकि आप secret को स्वयं manage किए बिना products, collections, और inventory manage कर सकें—या CSV या Excel file import कर सकें।

Authentication कैसे काम करता है?

एक server connector से

HTTPS पर किसी trusted backend से API कॉल करें। Authorization header में एक JSON string रखें:

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

store_owner_api_secrete public field name है, जिसमें historical spelling शामिल है। store_owner_api_secret भी स्वीकार किया जाता है। यह Bearer token नहीं है।

SiteChat admin से

Product Catalog page इसके बजाय आपका signed-in admin session भेजता है:

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

access_token को admin_auth_token के alias के रूप में स्वीकार किया जाता है।

store_key query parameter को header से match करना चाहिए। Owner secrets को केवल server-side environment variables में रखें—कभी भी storefront script, URL, या public repository में नहीं।

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

मैं products कैसे upload करूँ?

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"}
        }
      ]
    }
  ]
}

Required fields और नियम

• Required product fields: external_id, title, url, currency, price, और available। status का default published है।
• Optional inventory: tracks_inventory को true पर सेट करें और product या variant पर nonnegative quantity दें। इसके बाद Shoply stock से availability निकालता है (quantity > 0) और admin lists के लिए total_inventory store करता है।
• source catalog connection का नाम देता है (ज़रूरी नहीं कि कोई platform हो)। woocommerce-main जैसा एक stable नाम उपयोग करें। Allowed characters: lowercase letters, numbers, underscores, और hyphens; अधिकतम 64 characters। Admin में form-created products का default source admin होता है।
• Product identity, store, source, और external ID के संयोजन से बनती है। Batch और single POST upserts full replacements हैं, patches नहीं: छोड़े गए optional fields clear हो जाते हैं। Partial updates के लिए PATCH उपयोग करें।
• Batches में 1–50 products हो सकते हैं और अधिकतम 2,000,000 request bytes। प्रत्येक product का validated JSON 128,000 bytes तक सीमित है, और अधिकतम 250 variants हो सकते हैं।
• Prices के लिए decimal strings को प्राथमिकता दें। Currency तीन-अक्षरी uppercase code होनी चाहिए।
• Product और image URLs HTTP(S) होने चाहिए। Importing आपके लिए उन URLs को fetch नहीं करता।
• Searchable product specs के लिए public metafields उपयोग करें (SiteChat का Shopify product metafields के समान संस्करण)। Values plain strings होनी चाहिए। Legacy attributes को alias के रूप में स्वीकार किया जाता है। Private product metadata अब समर्थित नहीं है।
• draft और archived products अगले published index से बाहर रखे जाते हैं। Sold-out published products indexed रहते हैं और उनके साथ availability जुड़ी रहती है।
• Manual collections में title, description, status, और product memberships (source + external_id) की सूची store होती है। इस release में smart/rule-based collections समर्थित नहीं हैं।

Sample success response

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

Shoply लिखने से पहले पूरे request को validate करता है। HTTP 200 फिर भी कुछ failed results को error: "storage_error" के साथ सूचीबद्ध कर सकता है। हर result की जाँच करें और failed products को retry करें। यदि index_status request_failed है, तो storage सफल हुआ लेकिन indexing schedule नहीं हुई—store किए गए products को भी फिर से retry करें।

Python example

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

मैं imported product को कैसे verify करूँ?

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

वही Authorization header उपयोग करें। Response में schema_version, updated_at, index_status, और normalized product शामिल होते हैं। Missing records HTTP 404 लौटाते हैं।

Background indexer द्वारा rebuild publish करने के बाद, per-product readback status indexed, excluded (draft या archived products के लिए), या limit_exceeded हो जाता है। Admin listing के लिए GET /merchant/products/list उपयोग करें। अगले published index से किसी product को बाहर रखने के लिए DELETE /merchant/products से soft-archive करें (या status को archived / draft पर सेट करें); इस release में hard-delete उपलब्ध नहीं है।

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

क्या मैं product images अपलोड कर सकता हूँ?

हाँ। यदि कोई image पहले से किसी स्थायी public HTTPS URL पर उपलब्ध है, तो उस URL को product की images list या किसी variant के image field में रखें। Public S3 HTTPS URLs काम करते हैं। Raw s3:// paths और short-lived signed URLs काम नहीं करते।

यदि आप चाहते हैं कि Shoply file host करे, तो अपने backend से raw image bytes अपलोड करें:

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

Raw file bytes भेजें, JSON, base64, या multipart form data नहीं। JPEG, PNG, और WebP स्वीकार किए जाते हैं, अधिकतम 10 MiB और 20 million pixels तक। Animated images समर्थित नहीं हैं। Shoply image को WebP में convert करता है और embedded 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 लौटाता है। केवल image upload करने से वह किसी product से attach नहीं होती और indexing का अनुरोध भी नहीं होता। Returned URL को एक complete product में शामिल करें और उसे फिर से /merchant/products/batch के माध्यम से submit करें।

उसी account के लिए वही image फिर से upload करने पर उसका URL पुन: उपयोग होता है। बदली हुई image को नया URL मिलता है। इस release में image-delete endpoint उपलब्ध नहीं है।

Products chat और search में कब दिखाई देते हैं?

एक सफल batch save के बाद, Shoply background index rebuild का अनुरोध करता है। जब तक worker नया index publish नहीं कर देता, responses index_status: "pending" रिपोर्ट करती हैं। Completion time की कोई fixed guarantee नहीं है।

• Published products, product search और SiteChat chat द्वारा उपयोग किए जाने वाले knowledge—दोनों में प्रवेश करते हैं।
• Draft और archived products अगले rebuild में exclude कर दिए जाते हैं।
• यदि indexing schedule नहीं हुई (index_status: "request_failed"), तो उन products के लिए batch को retry करें जो पहले से सफलतापूर्वक store हो चुके हैं।

मुझे किन errors की अपेक्षा करनी चाहिए?

Secrets 90 days के बाद expire हो जाते हैं। Expiry से पहले Settings → Store owner API secret में replacement बनाएं, और जिस secret की अब आवश्यकता नहीं है उसे revoke करें। यही secret Merchant API guide में documented analytics, conversation, और knowledge endpoints को भी कॉल कर सकता है।

Integration में मदद के लिए, Shoply AI से संपर्क करें।