Jak nahrát svůj katalog pro SiteChat

Pokud používáte SiteChat na svém vlastním webu (nikoli v obchodě Shopify), můžete do Shoply odesílat strukturované záznamy produktů, aby je nakupující mohli najít v chatu SiteChat a ve vyhledávání produktů.

Tyto endpointy používají stejné Settings → Store owner API secret jako zbytek Shoply Merchant API a stránka Product Catalog v administraci SiteChat je může volat pomocí vašeho přístupového tokenu přihlášeného administrátora. Obchody Shopify nadále synchronizují katalogová data přes Shopify; tyto nahrávací trasy jsou dostupné pouze pro účty SiteChat, které ještě nesynchronizují katalog Magento.

V administraci SiteChat otevře Product Catalog oblast ve stylu Shopify s položkami Products, Collections a Inventory. Můžete přidávat nebo upravovat produkty, importovat CSV/Excel, seskupovat produkty do ručních kolekcí a upravovat skladová množství.

Jaká API jsou k dispozici?

Úspěšné uložení produktů požádá Shoply o přebudování indexu obchodu. Dokud toto přebudování neskončí, odpovědi uvádějí index_status: "pending". Publikované produkty se pak objeví jak v indexu produktů, tak ve znalostech používaných chatem SiteChat.

Kdo může tato API používat?

• Váš obchod musí být účet SiteChat (app_platform je SiteChat).
• Klíče obchodu Shopify (včetně jakékoli domény *.myshopify.com) jsou odmítány.
• Ověření musí používat buď platný tajný API klíč vlastníka obchodu, nebo přístupový token administrátora SiteChat přesně pro store_key v požadavku.
• Tokeny Shopify Admin API nemohou tyto trasy volat.

Vytvořte nebo obměňte tajný klíč vlastníka stejným způsobem jako u jiných integrací Merchant API: Jak používat Shoply Merchant API. V administrační konzoli SiteChat otevřete Product Catalog, kde můžete spravovat produkty, kolekce a skladové zásoby — nebo importovat soubor CSV či Excel — aniž byste museli sami pracovat s tajným klíčem.

Jak funguje ověřování?

Ze serverového konektoru

Volejte API z důvěryhodného backendu přes HTTPS. Do hlavičky Authorization vložte řetězec JSON:

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

store_owner_api_secrete je veřejný název pole, včetně historického pravopisu. store_owner_api_secret je také akceptován. Nejde o token typu Bearer.

Z administrace SiteChat

Stránka Product Catalog místo toho odesílá vaši přihlášenou administrátorskou relaci:

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

access_token je akceptován jako alias pro admin_auth_token.

Parametr dotazu store_key musí odpovídat hlavičce. Tajné klíče vlastníka uchovávejte pouze v proměnných prostředí na straně serveru — nikdy ne ve skriptu storefrontu, URL ani veřejném repozitáři.

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

Jak nahraji produkty?

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

Povinná pole a pravidla

• Povinná pole produktu: external_id, title, url, currency, price a available. status má výchozí hodnotu published.
• Volitelný inventář: nastavte tracks_inventory na true a nezáporné quantity na produktu nebo variantě. Shoply pak odvodí dostupnost ze zásob (quantity > 0) a uloží total_inventory pro seznamy v administraci.
• source pojmenovává připojení katalogu (ne nutně platformu). Použijte stabilní název, například woocommerce-main. Povolené znaky: malá písmena, čísla, podtržítka a pomlčky; až 64 znaků. Produkty vytvořené formulářem v administraci mají jako výchozí source admin.
• Identita produktu je kombinace obchodu, source a externího ID. Dávkové i jednotlivé POST upserty jsou plné náhrady, nikoli patche: vynechaná volitelná pole se vymažou. Pro částečné aktualizace použijte PATCH.
• Dávky obsahují 1–50 produktů a maximálně 2 000 000 bajtů požadavku. Validovaný JSON každého produktu je omezen na 128 000 bajtů, s nejvýše 250 variantami.
• Pro ceny preferujte desetinné řetězce. Měna je třípísmenný kód psaný velkými písmeny.
• URL produktů a obrázků musí být HTTP(S). Import za vás tyto URL nenačítá.
• Pro vyhledatelné specifikace produktů používejte veřejné metafields (analogii Shopify product metafields v SiteChat). Hodnoty musí být prosté řetězce. Starší attributes je akceptováno jako alias. Soukromá produktová metadata již nejsou podporována.
• Produkty draft a archived jsou vynechány z dalšího publikovaného indexu. Vyprodané publikované produkty zůstávají indexované s připojenou informací o dostupnosti.
• Ruční kolekce ukládají název, popis, stav a seznam členství produktů (source + external_id). Chytré kolekce / kolekce založené na pravidlech nejsou v této verzi podporovány.

Ukázka úspěšné odpovědi

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

Shoply před zápisem validuje celý požadavek. HTTP 200 může i tak obsahovat některé výsledky failed s error: "storage_error". Zkontrolujte každý výsledek a neúspěšné produkty zkuste znovu. Pokud je index_status request_failed, uložení proběhlo úspěšně, ale indexace nebyla naplánována — zkuste znovu také již uložené produkty.

Příklad v Pythonu

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

Jak ověřím importovaný produkt?

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

Použijte stejnou hlavičku Authorization. Odpověď obsahuje schema_version, updated_at, index_status a normalizovaný product. Chybějící záznamy vracejí HTTP 404.

Jakmile indexátor na pozadí zveřejní přebudovaný index, stav zpětného načtení jednotlivého produktu bude indexed, excluded (pro produkty draft nebo archived) nebo limit_exceeded. Pro výpis v administraci použijte GET /merchant/products/list. K měkké archivaci použijte DELETE /merchant/products (nebo nastavte status na archived / draft), chcete-li produkt udržet mimo další publikovaný index; v této verzi není k dispozici 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"])

Jak bezpečně aktualizuji varianty nebo metafieldy?

Pro PATCH obsahující variants, metafields nebo starší pole attributes nejprve načtěte produkt pomocí GET. Sestavte úpravu z této odpovědi a do těla PATCH zahrňte její hodnotu nejvyšší úrovně updated_at jako expected_updated_at. To platí i při vymazání variant nebo metafieldů.

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 znamená, že verze chyběla nebo jiná aktualizace produkt změnila. Před opakováním načtěte nejnovější verzi produktu a znovu sloučte zamýšlené změny. Nepřipojujte novou verzi ke starému seznamu variant: mohlo by to přepsat novější hodnoty skladových zásob.

Stávající integrace, které PATCHují tato pole bez verze, musí být aktualizovány. PATCH požadavky pouze se skalárními hodnotami, vyhrazené úpravy inventáře a plné náhrady přes POST nebo dávkový import toto pole nevyžadují. Plné náhrady přesto nahrazují celý produkt.

Mohu nahrávat obrázky produktů?

Ano. Pokud je obrázek již dostupný na trvalé veřejné HTTPS URL, vložte tuto URL do seznamu images produktu nebo do pole image varianty. Veřejné HTTPS URL ze S3 fungují. Nezpracované cesty s3:// a krátkodobé podepsané URL ne.

Pokud chcete, aby soubor hostovalo Shoply, nahrajte surové bajty obrázku ze svého backendu:

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

Pošlete surové bajty souboru, nikoli JSON, base64 ani multipart form data. Jsou přijímány JPEG, PNG a WebP, do velikosti 10 MiB a 20 milionů pixelů. Animované obrázky nejsou podporovány. Shoply převede obrázek na WebP a odstraní vložená 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 vrací url, content_type, size_bytes, width a height. Samotné nahrání obrázku jej nepřipojí k produktu ani nevyžádá indexaci. Zahrňte vrácenou URL do kompletního produktu a odešlete jej znovu přes /merchant/products/batch.

Stejný obrázek nahraný znovu pro stejný účet znovu použije svou URL. Změněný obrázek dostane novou URL. V této verzi není endpoint pro mazání obrázků.

Kdy se produkty objeví v chatu a vyhledávání?

Po úspěšném uložení dávky Shoply požádá o přebudování indexu na pozadí. Odpovědi uvádějí index_status: "pending", dokud worker nezveřejní nový index. Neexistuje žádná pevná záruka doby dokončení.

• Publikované produkty vstupují jak do vyhledávání produktů, tak do znalostí používaných chatem SiteChat.
• Produkty draft a archived jsou při dalším přebudování vynechány.
• Pokud indexace nebyla naplánována (index_status: "request_failed"), zopakujte dávku pro produkty, které už byly úspěšně uloženy.

Jaké chyby mám očekávat?

Platnost tajných klíčů končí po 90 dnech. Před vypršením vytvořte náhradu v Settings → Store owner API secret a odvolejte všechny tajné klíče, které již nepotřebujete. Stejný tajný klíč může také volat endpointy analytiky, konverzací a znalostí zdokumentované v průvodci Merchant API.

Pokud potřebujete pomoc s integrací, kontaktujte Shoply AI.