Kako naložiti svoj katalog za SiteChat

Če uporabljate SiteChat na svojem spletnem mestu (ne v trgovini Shopify), lahko v Shoply pošljete strukturirane zapise izdelkov, da jih bodo kupci lahko našli v klepetu SiteChat in pri iskanju izdelkov.

Te končne točke uporabljajo isti Settings → Store owner API secret kot preostali del Shoply Merchant API, stran Product Catalog v skrbniškem vmesniku SiteChat pa jih lahko kliče z vašim prijavljenim skrbniškim žetonom za dostop. Trgovine Shopify še naprej sinhronizirajo podatke kataloga prek Shopifyja; te poti za nalaganje so na voljo samo za račune SiteChat, ki še ne sinhronizirajo kataloga Magento.

V skrbniškem vmesniku SiteChat Product Catalog odpre območje v slogu Shopify z razdelki Products, Collections in Inventory. Dodajate ali urejate lahko izdelke, uvozite CSV/Excel, združujete izdelke v ročne zbirke in prilagajate količine zaloge.

Kateri API-ji so na voljo?

Uspešna shranjevanja izdelkov zahtevajo od Shoplyja, da znova zgradi indeks trgovine. Dokler ta ponovna izgradnja ni dokončana, odgovori poročajo index_status: "pending". Objavljeni izdelki se nato pojavijo tako v indeksu izdelkov kot tudi v znanju, ki ga uporablja klepet SiteChat.

Kdo lahko uporablja te API-je?

• Vaša trgovina mora biti račun SiteChat (app_platform je SiteChat).
• Ključi trgovine Shopify (vključno s katerokoli domeno *.myshopify.com) so zavrnjeni.
• Preverjanje pristnosti mora uporabljati veljaven skrivni API-ključ lastnika trgovine ali skrbniški žeton za dostop SiteChat za točen store_key v zahtevi.
• Žetoni Shopify Admin API ne morejo klicati teh poti.

Ustvarite ali zamenjajte skrivnost lastnika na enak način kot pri drugih integracijah Merchant API: How to Use the Shoply Merchant API. V skrbniški konzoli SiteChat odprite Product Catalog, da upravljate izdelke, zbirke in zalogo — ali uvozite datoteko CSV ali Excel — brez lastnega upravljanja skrivnega ključa.

Kako deluje preverjanje pristnosti?

Iz strežniškega konektorja

API pokličite iz zaupanja vrednega zaledja prek HTTPS. V glavo Authorization vstavite niz JSON:

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

store_owner_api_secrete je javno ime polja, vključno z zgodovinskim črkovanjem. Sprejet je tudi store_owner_api_secret. To ni žeton Bearer.

Iz skrbniškega vmesnika SiteChat

Stran Product Catalog namesto tega pošlje vašo prijavljeno skrbniško sejo:

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

access_token je sprejet kot vzdevek za admin_auth_token.

Poizvedbeni parameter store_key se mora ujemati z glavo. Skrivne ključe lastnika hranite samo v strežniških okoljskih spremenljivkah — nikoli v skriptu trgovine, URL-ju ali javnem repozitoriju.

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

Kako naložim izdelke?

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

Zahtevana polja in pravila

• Zahtevana polja izdelka: external_id, title, url, currency, price in available. status je privzeto nastavljen na published.
• Izbirna zaloga: nastavite tracks_inventory na true in nenegativno quantity na izdelku ali varianti. Shoply nato razpoložljivost izpelje iz zaloge (quantity > 0) in shrani total_inventory za skrbniške sezname.
• source poimenuje povezavo kataloga (ni nujno platforma). Uporabite stabilno ime, kot je woocommerce-main. Dovoljeni znaki: male črke, številke, podčrtaji in vezaji; do 64 znakov. Izdelki, ustvarjeni prek obrazca v skrbniškem vmesniku, imajo privzeto vir admin.
• Identiteta izdelka je kombinacija trgovine, vira in zunanjega ID-ja. Paketni in enojni POST upserti so popolne zamenjave, ne popravki: izpuščena izbirna polja se počistijo. Za delne posodobitve uporabite PATCH.
• Paketi vsebujejo 1–50 izdelkov in največ 2.000.000 bajtov zahteve. Potrjeni JSON vsakega izdelka je omejen na 128.000 bajtov in največ 250 variant.
• Za cene raje uporabite decimalne nize. Valuta je trimestna koda z velikimi črkami.
• URL-ji izdelkov in slik morajo biti HTTP(S). Uvoz teh URL-jev ne pridobi namesto vas.
• Uporabite javna metafields za iskane specifikacije izdelkov (analogija SiteChat za metafields izdelkov v Shopifyju). Vrednosti morajo biti navadni nizi. Zastarela attributes so sprejeta kot vzdevek. Zasebni metadata izdelka niso več podprti.
• Izdelki draft in archived so izpuščeni iz naslednjega objavljenega indeksa. Razprodani objavljeni izdelki ostanejo indeksirani z dodano razpoložljivostjo.
• Ročne zbirke shranjujejo naslov, opis, status in seznam članstev izdelkov (source + external_id). Pametne/z pravilih podprte zbirke v tej izdaji niso podprte.

Vzorčni uspešen odgovor

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

Shoply pred zapisom potrdi celotno zahtevo. HTTP 200 lahko še vedno navede nekatere rezultate failed z error: "storage_error". Preglejte vsak rezultat in ponovno poskusite za neuspele izdelke. Če je index_status request_failed, je bilo shranjevanje uspešno, vendar indeksiranje ni bilo načrtovano — tudi že shranjene izdelke pošljite znova.

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

Kako preverim uvožen izdelek?

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

Uporabite isto glavo Authorization. Odgovor vključuje schema_version, updated_at, index_status in normaliziran product. Manjkajoči zapisi vrnejo HTTP 404.

Ko indeksator v ozadju objavi ponovno izgradnjo, status povratnega branja posameznega izdelka postane indexed, excluded (za izdelke v stanju draft ali archived) ali limit_exceeded. Za skrbniški seznam uporabite GET /merchant/products/list. Mehko arhivirajte z DELETE /merchant/products (ali nastavite status na archived / draft), da izdelek ne bo vključen v naslednji objavljeni indeks; v tej izdaji ni trajnega brisanja.

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

Kako varno posodobim variante ali metafields?

Za PATCH, ki vsebuje variants, metafields ali zastarelo polje attributes, najprej preberite izdelek z GET. Zgradite urejanje iz tega odgovora in vključite njegovo vrhnjo vrednost updated_at kot expected_updated_at v telo PATCH. To velja tudi pri brisanju variant ali metafields.

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 pomeni, da je različica manjkala ali da je druga posodobitev spremenila izdelek. Preberite najnovejši izdelek in pred ponovnim poskusom znova združite svoje predvidene spremembe. Ne pripenjajte nove različice na star seznam variant: to bi lahko prepisalo novejše vrednosti zaloge.

Obstoječe integracije, ki izvajajo PATCH teh polj brez različice, je treba posodobiti. Zahteve PATCH samo s skalarnimi vrednostmi, namenske prilagoditve zaloge in popolne zamenjave prek POST ali paketnega uvoza tega polja ne zahtevajo. Popolne zamenjave še vedno zamenjajo celoten izdelek.

Ali lahko naložim slike izdelkov?

Da. Če je slika že na voljo na trajnem javnem URL-ju HTTPS, ta URL vstavite v seznam images izdelka ali v polje image variante. Javni URL-ji HTTPS na S3 delujejo. Neobdelane poti s3:// in kratkotrajni podpisani URL-ji ne delujejo.

Če želite, da datoteko gosti Shoply, iz svojega zaledja naložite surove bajte slike:

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

Pošljite surove bajte datoteke, ne JSON, base64 ali podatke obrazca multipart. Sprejeti so JPEG, PNG in WebP, do 10 MiB in 20 milijonov slikovnih pik. Animirane slike niso podprte. Shoply pretvori sliko v WebP in odstrani vdelane metapodatke.

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 vrne url, content_type, size_bytes, width in height. Samostojno nalaganje slike je ne pripne izdelku in ne zahteva indeksiranja. Vključite vrnjeni URL v celoten izdelek in ga znova pošljite prek /merchant/products/batch.

Če isto sliko znova naložite za isti račun, se njen URL ponovno uporabi. Spremenjena slika prejme nov URL. V tej izdaji ni končne točke za brisanje slik.

Kdaj se izdelki pojavijo v klepetu in iskanju?

Po uspešnem paketnem shranjevanju Shoply zahteva ponovno izgradnjo indeksa v ozadju. Odgovori poročajo index_status: "pending", dokler delovni proces ne objavi novega indeksa. Ni fiksnega jamstva glede časa dokončanja.

• Objavljeni izdelki vstopijo tako v iskanje izdelkov kot v znanje, ki ga uporablja klepet SiteChat.
• Izdelki v stanju draft in archived so pri naslednji ponovni izgradnji izključeni.
• Če indeksiranje ni bilo načrtovano (index_status: "request_failed"), ponovno pošljite paket za izdelke, ki so se že uspešno shranili.

Katere napake lahko pričakujem?

Skrivni ključi potečejo po 90 dneh. Pred potekom ustvarite zamenjavo v Settings → Store owner API secret in prekličite vsak skrivni ključ, ki ga ne potrebujete več. Isti skrivni ključ lahko kliče tudi končne točke za analitiko, pogovore in znanje, dokumentirane v Merchant API guide.

Za pomoč pri integraciji kontaktirajte Shoply AI.