Jak nahrát 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 zákazníci 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 administrátora po přihlášení. Obchody Shopify nadále synchronizují data katalogu přes Shopify; tyto cesty pro nahrávání jsou dostupné pouze pro účty SiteChat, které už nesynchronizují katalog Magento.

V administraci SiteChat otevírá 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í produktu požádá Shoply o přebudování indexu obchodu. Dokud toto přebudování neskončí, odpovědi hlásí index_status: "pending". Publikované produkty se pak zobrazí 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 obchodů Shopify (včetně jakékoli domény *.myshopify.com) jsou odmítnuty.
• Ověření musí používat buď platný tajný klíč API vlastníka obchodu, nebo přístupový token administrátora SiteChat pro přesný store_key v požadavku.
• Tokeny Shopify Admin API nemohou tyto cesty volat.

Vytvořte nebo obnovte tajný klíč vlastníka stejným způsobem jako u jiných integrací Merchant API: Jak používat Shoply Merchant API. V administraci SiteChat otevřete Product Catalog, kde můžete spravovat produkty, kolekce a skladové zásoby — nebo importovat soubor CSV či Excel — bez nutnosti spravovat tajný klíč ručně.

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 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 přijímá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 nebo 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 se výchozím nastavením nastaví na published.
• Volitelný sklad: nastavte tracks_inventory na true a nezáporné quantity na produktu nebo variantě. Shoply pak odvodí dostupnost ze skladu (quantity > 0) a uloží total_inventory pro seznamy v administraci.
• source pojmenovává připojení katalogu (nemusí to být platforma). Použijte stabilní název, například woocommerce-main. Povolené znaky: malá písmena, čísla, podtržítka a spojovníky; maximálně 64 znaků. Produkty vytvořené formulářem v administraci mají ve výchozím nastavení source admin.
• Identita produktu je kombinace obchodu, source a externího ID. Batch 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 maximálně 250 variantami.
• Pro ceny preferujte desetinné řetězce. Měna je třípísmenný kód velkými písmeny.
• URL produktů a obrázků musí být HTTP(S). Import za vás tyto URL nestahuje.
• Pro veřejné metafields používejte vyhledatelné specifikace produktů (obdoba metafieldů produktů Shopify v SiteChat). Hodnoty musí být prosté řetězce. Starší attributes jsou akceptovány jako alias. Soukromá produktová metadata už 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 dostupností.
• Ruční kolekce ukládají title, description, status a seznam členství produktů (source + external_id). Chytré/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 přesto obsahovat některé výsledky failed s error: "storage_error". Zkontrolujte každý výsledek a neúspěšné produkty odešlete znovu. Pokud je index_status request_failed, uložení proběhlo úspěšně, ale indexování nebylo naplánováno — znovu odešlete i 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 vrací HTTP 404.

Poté, co indexer na pozadí publikuje přebudování, se stav čtení jednotlivého produktu změní na indexed, excluded (pro produkty draft nebo archived) nebo limit_exceeded. Pro výpis v administraci použijte GET /merchant/products/list. Měkce archivujte pomocí DELETE /merchant/products (nebo nastavte status na archived / draft), pokud chcete produkt vynechat z dalšího publikovaného indexu; 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"])

Mohu nahrávat obrázky produktů?

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

Pokud chcete, aby soubor hostoval Shoply, nahrajte nezpracované 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

Odešlete nezpracované bajty souboru, nikoli JSON, base64 ani multipart form data. Jsou podporovány JPEG, PNG a WebP, do velikosti 10 MiB a 20 milionů pixelů. Animované obrázky nejsou podporovány. Shoply obrázek převede do 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 ho nepřipojí k produktu ani nevyžádá indexování. Zahrňte vrácenou URL do kompletního produktu a znovu jej odešlete přes /merchant/products/batch.

Pokud se stejný obrázek nahraje znovu pro stejný účet, použije se znovu jeho URL. Změněný obrázek dostane novou URL. V této verzi neexistuje endpoint pro smazání obrázku.

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

Po úspěšném uložení dávky Shoply vyžádá přebudování indexu na pozadí. Odpovědi hlásí index_status: "pending", dokud worker nezveřejní nový index. Neexistuje 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í vyloučeny.
• Pokud indexování nebylo naplánováno (index_status: "request_failed"), odešlete dávku znovu pro produkty, které už byly úspěšně uloženy.

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

Tajné klíče vyprší po 90 dnech. Před vypršením vytvořte náhradu v Settings → Store owner API secret a zrušte všechny tajné klíče, které už nepotřebujete. Stejný tajný klíč může také volat endpointy pro analytiku, konverzace a znalosti zdokumentované v průvodci Merchant API.

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