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

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

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

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

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

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

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

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

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

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

Server connector से

API को HTTPS पर किसी trusted backend से call करें। 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 पेज आपकी 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: product या variant पर tracks_inventory को true और quantity को nonnegative मान पर सेट करें। इसके बाद Shoply stock से availability derive करता है (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 के combination से बनती है। 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) होने चाहिए। Import करने से वे URLs आपके लिए fetch नहीं किए जाते।
• Searchable product specs के लिए public metafields उपयोग करें (SiteChat में Shopify product metafields के समकक्ष)। Values plain strings होनी चाहिए। Legacy attributes को alias के रूप में स्वीकार किया जाता है। Private product metadata अब supported नहीं है।
• draft और archived products को अगले published index में शामिल नहीं किया जाता। Sold-out published products availability के साथ indexed रहते हैं।
• Manual collections में title, description, status, और product memberships (source + external_id) की सूची store होती है। इस release में smart/rule-based collections supported नहीं हैं।

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" के साथ listed हो सकते हैं। हर result की जाँच करें और failed products को retry करें। यदि index_status request_failed है, तो storage सफल रहा लेकिन indexing schedule नहीं हुई — stored products को भी फिर से retry करें।

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

मैं imported product का सत्यापन कैसे करूँ?

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 return होता है।

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

मैं variants या metafields को सुरक्षित रूप से कैसे update करूँ?

यदि किसी PATCH में variants, metafields, या legacy attributes field शामिल है, तो पहले GET के साथ product पढ़ें। उस response से edit तैयार करें और PATCH body में उसके top-level updated_at value को expected_updated_at के रूप में शामिल करें। यह variants या metafields को clear करते समय भी लागू होता है।

current_response = requests.get(
    "https://api.shoplyai.ai/merchant/products",
    params={"store_key": store_key, "source": "woocommerce-main", "external_id": "123"},
    headers=headers,
    timeout=30,
)
current_response.raise_for_status()
current = current_response.json()
updated_metafields = {**current["product"].get("metafields", {}), "material": "Leather"}
response = requests.patch(
    "https://api.shoplyai.ai/merchant/products",
    params={"store_key": store_key},
    headers=headers,
    json={
        "source": "woocommerce-main",
        "external_id": "123",
        "expected_updated_at": current["updated_at"],
        "metafields": updated_metafields,
    },
    timeout=30,
)
response.raise_for_status()

HTTP 409 का अर्थ है कि version missing था या किसी अन्य update ने product बदल दिया। Retry करने से पहले नवीनतम product पढ़ें और अपने इच्छित changes को फिर से merge करें। पुराने variants list के साथ नया version attach न करें: इससे नए stock values overwrite हो सकते हैं।

जो existing integrations बिना version के इन fields पर PATCH करती हैं, उन्हें update करना होगा। केवल scalar-only PATCH requests, dedicated inventory adjustments, और POST या batch import के माध्यम से full replacements के लिए यह field आवश्यक नहीं है। Full replacements फिर भी पूरे product को replace करते हैं।

क्या मैं product images upload कर सकता हूँ?

हाँ। यदि कोई 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 upload करें:

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 supported नहीं हैं। 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 return होते हैं। केवल image upload करने से वह किसी product से attach नहीं होती और न ही indexing का अनुरोध होता है। Returned URL को किसी complete product में शामिल करें और उसे फिर से /merchant/products/batch के माध्यम से submit करें।

उसी account के लिए वही image दोबारा upload करने पर उसका URL reuse होता है। बदली हुई 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 में excluded रहते हैं।
• यदि 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 को भी call कर सकता है।

Integration में सहायता के लिए, Shoply AI से संपर्क करें।