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 o izdelkih, da jih kupci lahko najdejo 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štvu 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štvu SiteChat možnost Product Catalog odpre območje v slogu Shopify z razdelki Products, Collections in Inventory. Dodajate ali urejate lahko izdelke, uvažate CSV/Excel, združujete izdelke v ročne zbirke in prilagajate količine zaloge.

Kateri API-ji so na voljo?

Uspešna shranjevanja izdelkov od Shoplyja zahtevajo ponovno izgradnjo indeksa trgovine. Dokler ta ponovna izgradnja ni konč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 bodisi veljaven skrivni ključ API-ja lastnika trgovine bodisi skrbniški žeton za dostop SiteChat za točen store_key v zahtevi.
• Žetoni Shopify Admin API teh poti ne morejo klicati.

Skrivni ključ lastnika ustvarite ali zamenjate 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 — ne da bi sami upravljali skrivni ključ.

Kako deluje preverjanje pristnosti?

Iz strežniškega povezovalnika

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štva 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 izložbe, 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"}
        }
      ]
    }
  ]
}

Obvezna polja in pravila

• Obvezna polja izdelka: external_id, title, url, currency, price in available. status privzeto uporablja vrednost published.
• Izbirna zaloga: nastavite tracks_inventory na true in nenegativno quantity na izdelku ali varianti. Shoply nato izpelje razpoložljivost iz zaloge (quantity > 0) in shrani total_inventory za skrbniške sezname.
• source poimenuje povezavo s katalogom (ne nujno platforme). 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štvu, imajo privzeto vir admin.
• Identiteta izdelka je kombinacija trgovine, vira in zunanjega ID-ja. Paketni in posamezni 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 posameznega izdelka je omejen na 128.000 bajtov, z največ 250 variantami.
• Za cene raje uporabite decimalne nize. Valuta je tričrkovna koda z velikimi črkami.
• URL-ji izdelkov in slik morajo biti HTTP(S). Uvoz teh URL-jev ne pridobi namesto vas.
• Za iskane specifikacije izdelkov uporabite javna metafields (analogija SiteChat za Shopifyjeva metafields izdelkov). Vrednosti morajo biti navadni nizi. Starejši attributes je sprejet kot vzdevek. Zasebni metadata izdelka ni več podprt.
• Izdelki draft in archived so izpuščeni iz naslednjega objavljenega indeksa. Razprodani objavljeni izdelki ostanejo indeksirani s pripeto razpoložljivostjo.
• Ročne zbirke shranjujejo naslov, opis, stanje in seznam članstev izdelkov (source + external_id). Pametne/z na pravilih temelječe zbirke v tej izdaji niso podprte.

Primer uspešnega odgovora

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

Shoply potrdi celotno zahtevo pred zapisovanjem. HTTP 200 lahko še vedno vsebuje 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 razporejeno — ponovno pošljite tudi že shranjene izdelke.

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 indeksirnik v ozadju objavi ponovno izgradnjo, stanje povratnega branja na posamezen izdelek postane indexed, excluded (za izdelke 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 ostane izven naslednjega objavljenega indeksa; v tej izdaji trdi izbris ni na voljo.

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

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 S3 delujejo. Surove poti s3:// in kratkotrajni podpisani URL-ji ne.

Č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 večdelnih obrazčnih podatkov. 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. Vrnjeni URL vključite v celoten izdelek in ga znova oddajte prek /merchant/products/batch.

Če je ista slika znova naložena 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 delavec 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 Draft in Archived so pri naslednji ponovni izgradnji izključeni.
• Če indeksiranje ni bilo razporejeno (index_status: "request_failed"), ponovno pošljite paket za izdelke, ki so bili že uspešno shranjeni.

Katere napake lahko pričakujem?

Skrivni ključi potečejo po 90 dneh. Pred potekom ustvarite nadomestnega v Settings → Store owner API secret in prekličite vse skrivne ključe, ki jih 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 stopite v stik s Shoply AI.