Kaip įkelti savo katalogą į SiteChat

Jei naudojate SiteChat savo svetainėje (ne Shopify parduotuvėje), galite siųsti struktūrinius produktų įrašus į Shoply, kad pirkėjai galėtų juos rasti SiteChat pokalbyje ir produktų paieškoje.

Šie galiniai taškai naudoja tą patį Settings → Store owner API secret kaip ir likusi Shoply Merchant API, o SiteChat administravimo Product Catalog puslapis gali juos iškviesti naudodamas jūsų prisijungusio administratoriaus prieigos raktą. Shopify parduotuvės toliau sinchronizuoja katalogo duomenis per Shopify; šie įkėlimo maršrutai prieinami tik SiteChat paskyroms, kurios dar nesinchronizuoja Magento katalogo.

SiteChat administravimo skiltyje Product Catalog atveria į Shopify panašią sritį su Products, Collections ir Inventory. Galite pridėti arba redaguoti produktus, importuoti CSV/Excel, grupuoti produktus į rankines kolekcijas ir koreguoti atsargų kiekius.

Kokie API yra prieinami?

Sėkmingai išsaugojus produktus, Shoply paprašoma perkurti parduotuvės indeksą. Kol tas perkūrimas nebaigtas, atsakymuose rodoma index_status: "pending". Tada publikuoti produktai pasirodo tiek produktų indekse, tiek žiniose, kurias naudoja SiteChat pokalbis.

Kas gali naudoti šiuos API?

• Jūsų parduotuvė turi būti SiteChat paskyra (app_platform yra SiteChat).
• Shopify parduotuvės raktai (įskaitant bet kokį *.myshopify.com domeną) atmetami.
• Autentifikavimas turi naudoti arba galiojantį parduotuvės savininko API slaptą raktą, arba SiteChat administratoriaus prieigos raktą tiksliai tam store_key, kuris nurodytas užklausoje.
• Shopify Admin API raktai negali iškviesti šių maršrutų.

Sukurkite arba pakeiskite savininko slaptą raktą taip pat, kaip ir kitoms Merchant API integracijoms: Kaip naudoti Shoply Merchant API. SiteChat administravimo konsolėje atidarykite Product Catalog, kad valdytumėte produktus, kolekcijas ir atsargas arba importuotumėte CSV ar Excel failą patys nevaldydami slapto rakto.

Kaip veikia autentifikavimas?

Iš serverio jungties

Iškvieskite API iš patikimos serverio pusės sistemos per HTTPS. Įdėkite JSON eilutę į Authorization antraštę:

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

store_owner_api_secrete yra viešas lauko pavadinimas, įskaitant istorinę rašybą. store_owner_api_secret taip pat priimamas. Tai nėra Bearer raktas.

Iš SiteChat administravimo aplinkos

Product Catalog puslapis vietoj to siunčia jūsų prisijungusio administratoriaus sesiją:

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

access_token priimamas kaip admin_auth_token aliasas.

store_key užklausos parametras turi sutapti su antrašte. Savininko slaptus raktus laikykite tik serverio pusės aplinkos kintamuosiuose — niekada ne vitrinos scenarijuje, URL ar viešoje saugykloje.

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

Kaip įkelti produktus?

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

Privalomi laukai ir taisyklės

• Privalomi produkto laukai: external_id, title, url, currency, price ir available. status numatytoji reikšmė yra published.
• Pasirenkamos atsargos: nustatykite tracks_inventory į true ir neneigiamą quantity produktui arba variantui. Tada Shoply išveda prieinamumą iš atsargų (quantity > 0) ir saugo total_inventory administratoriaus sąrašams.
• source nurodo katalogo jungtį (nebūtinai platformą). Naudokite stabilų pavadinimą, pvz., woocommerce-main. Leidžiami simboliai: mažosios raidės, skaičiai, apatiniai brūkšniai ir brūkšneliai; iki 64 simbolių. Administravimo aplinkoje formomis sukurti produktai pagal nutylėjimą naudoja source admin.
• Produkto tapatybė yra parduotuvės, source ir išorinio ID kombinacija. Paketinis ir vienetinis POST upsert yra visiški pakeitimai, o ne pataisos: praleisti pasirenkami laukai išvalomi. Daliniams atnaujinimams naudokite PATCH.
• Paketai turi 1–50 produktų ir ne daugiau kaip 2 000 000 užklausos baitų. Kiekvieno produkto patvirtintas JSON ribojamas iki 128 000 baitų, su ne daugiau kaip 250 variantų.
• Kainoms teikite pirmenybę dešimtainėms eilutėms. Valiuta yra trijų raidžių didžiosiomis raidėmis rašomas kodas.
• Produkto ir vaizdų URL turi būti HTTP(S). Importavimas šių URL jūsų vardu neatsiunčia.
• Naudokite viešus metafields ieškomoms produkto specifikacijoms (SiteChat analogas Shopify produkto metafields). Reikšmės turi būti paprastos eilutės. Senasis attributes priimamas kaip aliasas. Privatūs produkto metadata nebepalaikomi.
• draft ir archived produktai neįtraukiami į kitą publikuotą indeksą. Išparduoti publikuoti produktai lieka indeksuoti su pridėta prieinamumo informacija.
• Rankinės kolekcijos saugo pavadinimą, aprašą, būseną ir produktų narystės sąrašą (source + external_id). Šioje versijoje išmaniosios / taisyklėmis pagrįstos kolekcijos nepalaikomos.

Sėkmingo atsakymo pavyzdys

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

Shoply prieš rašydama patikrina visą užklausą. HTTP 200 vis tiek gali išvardyti kai kuriuos failed rezultatus su error: "storage_error". Patikrinkite kiekvieną rezultatą ir pakartokite nesėkmingų produktų siuntimą. Jei index_status yra request_failed, saugojimas pavyko, bet indeksavimas nebuvo suplanuotas — taip pat pakartokite jau išsaugotus produktus.

Python pavyzdys

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

Kaip patikrinti importuotą produktą?

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

Naudokite tą pačią Authorization antraštę. Atsakyme pateikiami schema_version, updated_at, index_status ir normalizuotas product. Trūkstami įrašai grąžina HTTP 404.

Kai foninis indeksuotojas paskelbia perkurtą indeksą, vieno produkto nuskaitymo būsena tampa indexed, excluded (juodraščiams ar archyvuotiems produktams) arba limit_exceeded. Administratoriaus sąrašui naudokite GET /merchant/products/list. Minkštai archyvuokite su DELETE /merchant/products (arba nustatykite status į archived / draft), kad produktas nepatektų į kitą publikuotą indeksą; šioje versijoje nėra galimybės visiškai ištrinti.

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

Kaip saugiai atnaujinti variantus arba metafields?

Atliekant PATCH, kuriame yra variants, metafields arba senasis laukas attributes, pirmiausia nuskaitykite produktą su GET. Sukurkite redagavimą pagal tą atsakymą ir įtraukite jo aukščiausio lygio updated_at reikšmę kaip expected_updated_at į PATCH turinį. Tai taip pat taikoma, kai išvalote variantus arba 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 reiškia, kad versijos trūko arba kitas atnaujinimas pakeitė produktą. Nuskaitykite naujausią produktą ir prieš kartodami dar kartą sujunkite numatytus pakeitimus. Nepridėkite naujos versijos prie seno variantų sąrašo: tai gali perrašyti naujesnes atsargų reikšmes.

Esamos integracijos, kurios atlieka PATCH šiems laukams be versijos, turi būti atnaujintos. PATCH užklausoms tik su skaliariniais laukais, atskiriems atsargų koregavimams ir visiškiems pakeitimams per POST ar paketinio importo užklausas šio lauko nereikia. Visiški pakeitimai vis tiek pakeičia visą produktą.

Ar galiu įkelti produktų vaizdus?

Taip. Jei vaizdas jau pasiekiamas nuolatiniu viešu HTTPS URL, įdėkite tą URL į produkto images sąrašą arba varianto image lauką. Vieši S3 HTTPS URL veikia. Neapdoroti s3:// keliai ir trumpalaikiai pasirašyti URL neveikia.

Jei norite, kad failą talpintų Shoply, įkelkite neapdorotus vaizdo baitus iš savo serverio pusės sistemos:

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

Siųskite neapdorotus failo baitus, o ne JSON, base64 ar multipart form data. Priimami JPEG, PNG ir WebP, iki 10 MiB ir 20 milijonų pikselių. Animuoti vaizdai nepalaikomi. Shoply konvertuoja vaizdą į WebP ir pašalina įterptus metaduomenis.

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 grąžina url, content_type, size_bytes, width ir height. Vien tik vaizdo įkėlimas jo nepriskiria produktui ir neprašo indeksavimo. Įtraukite grąžintą URL į pilną produktą ir pateikite jį dar kartą per /merchant/products/batch.

Tas pats vaizdas, įkeltas dar kartą tai pačiai paskyrai, pakartotinai naudoja savo URL. Pakeistas vaizdas gauna naują URL. Šioje versijoje nėra vaizdų šalinimo galinio taško.

Kada produktai pasirodo pokalbyje ir paieškoje?

Po sėkmingo paketinio išsaugojimo Shoply paprašo fone perkurti indeksą. Atsakymuose rodoma index_status: "pending", kol darbinis procesas paskelbia naują indeksą. Nėra fiksuotos užbaigimo laiko garantijos.

• Publikuoti produktai patenka ir į produktų paiešką, ir į žinių bazę, kurią naudoja SiteChat pokalbis.
• Juodraščiai ir archyvuoti produktai atmetami per kitą perkūrimą.
• Jei indeksavimas nebuvo suplanuotas (index_status: "request_failed"), pakartokite paketą tiems produktams, kurie jau buvo sėkmingai išsaugoti.

Kokių klaidų turėčiau tikėtis?

Slapti raktai nustoja galioti po 90 dienų. Sukurkite pakaitinį raktą skiltyje Settings → Store owner API secret prieš galiojimo pabaigą ir atšaukite visus raktus, kurių jums nebereikia. Tą patį slaptą raktą taip pat galima naudoti analytics, conversation ir knowledge galiniams taškams, aprašytiems Merchant API vadove.

Jei reikia pagalbos su integracija, susisiekite su Shoply AI.