Kaip įkelti savo katalogą į SiteChat

Jei naudojate SiteChat savo svetainėje (ne Shopify parduotuvėje), galite siųsti struktūrizuotus produktų įrašus į Shoply, kad pirkėjai galėtų juos rasti SiteChat pokalbiuose 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 kviesti naudodamas jūsų prisijungusio administratoriaus prieigos prieigos raktą. Shopify parduotuvės ir toliau sinchronizuoja katalogo duomenis per Shopify; šie įkėlimo maršrutai prieinami tik SiteChat paskyroms, kurios dar nesinchronizuoja Magento katalogo.

SiteChat administravimo aplinkoje 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šsaugant produktus, Shoply paprašo perkurti parduotuvės indeksą. Kol šis perkūrimas nebaigtas, atsakymuose nurodoma index_status: "pending". Tada paskelbti produktai pasirodo ir produktų indekse, ir žiniose, kurias naudoja SiteChat pokalbiai.

Kas gali naudoti šiuos API?

• Jūsų parduotuvė turi būti SiteChat paskyra (app_platform yra SiteChat).
• Shopify parduotuvės raktai (įskaitant bet kurį *.myshopify.com domeną) atmetami.
• Autentifikavimas turi naudoti arba galiojantį parduotuvės savininko API slaptą raktą, arba SiteChat administratoriaus prieigos prieigos raktą, skirtą tiksliai tam store_key, kuris yra užklausoje.
• Shopify Admin API prieigos raktai negali 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ą — patiems tvarkyti slapto rakto nereikės.

Kaip veikia autentifikavimas?

Iš serverio jungties

Kvieskite API iš patikimos galinė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ą. Taip pat priimamas store_owner_api_secret. Tai nėra Bearer prieigos raktas.

Iš SiteChat administravimo aplinkos

Product Catalog puslapis vietoje 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 sinonimas.

store_key užklausos parametro reikšmė 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 numatytai yra published.
• Pasirenkamos atsargos: nustatykite tracks_inventory į true ir neneigiamą quantity produkto arba varianto lygiu. Tada Shoply apskaičiuoja prieinamumą pagal atsargas (quantity > 0) ir saugo total_inventory administravimo sąrašams.
• source nurodo katalogo ryšį (nebūtinai platformą). Naudokite stabilų pavadinimą, pvz., woocommerce-main. Leidžiami simboliai: mažosios raidės, skaičiai, pabraukimai ir brūkšneliai; iki 64 simbolių. Administravimo aplinkoje formomis sukurti produktai pagal numatymą naudoja source admin.
• Produkto tapatybė yra parduotuvės, source ir išorinio ID kombinacija. Paketinis ir vieno produkto POST upsert yra visiški pakeitimai, o ne daliniai atnaujinimai: praleisti pasirenkami laukai išvalomi. Daliniams atnaujinimams naudokite PATCH.
• Paketai turi turėti 1–50 produktų ir daugiausia 2 000 000 užklausos baitų. Kiekvieno produkto patvirtintas JSON ribojamas iki 128 000 baitų, daugiausia su 250 variantų.
• Kainoms teikite pirmenybę dešimtainėms eilutėms. Valiuta yra trijų raidžių kodas didžiosiomis raidėmis.
• Produktų ir vaizdų URL turi būti HTTP(S). Importavimas šių URL už jus neatsisiunčia.
• Naudokite viešus metafields paieškai tinkamoms produkto specifikacijoms (SiteChat atitikmuo Shopify produkto metafields). Reikšmės turi būti paprastos eilutės. Senasis attributes taip pat priimamas kaip sinonimas. Privatūs produkto metadata nebepalaikomi.
• draft ir archived produktai neįtraukiami į kitą paskelbtą indeksą. Išparduoti paskelbti produktai lieka indeksuoti su pridėta prieinamumo informacija.
• Rankinės kolekcijos saugo pavadinimą, aprašymą, būseną ir produktų narystės sąrašą (source + external_id). Išmaniosios / taisyklėmis paremtos kolekcijos šiame leidime 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 patikrina visą užklausą prieš ką nors įrašydama. HTTP 200 vis tiek gali pateikti kai kuriuos failed rezultatus su error: "storage_error". Patikrinkite kiekvieną rezultatą ir pakartokite nepavykusių produktų siuntimą. Jei index_status yra request_failed, saugojimas pavyko, bet indeksavimas nebuvo suplanuotas — pakartokite ir jau išsaugotų produktų siuntimą.

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. Jei įrašo nėra, grąžinamas HTTP 404.

Kai foninis indeksuotojas paskelbia perkurtą indeksą, vieno produkto nuskaitymo būsena tampa indexed, excluded (juodraštiniams arba archyvuotiems produktams) arba limit_exceeded. Administravimo sąrašui naudokite GET /merchant/products/list. Minkštai archyvuokite su DELETE /merchant/products (arba nustatykite status į archived / draft), kad produktas nepatektų į kitą paskelbtą indeksą; šiame leidime nėra galimybės atlikti visiško ištrynimo.

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

Ar galiu įkelti produktų vaizdus?

Taip. Jei vaizdas jau pasiekiamas per ilgalaikį viešą 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 galinė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 tą patį URL. Pakeistas vaizdas gauna naują URL. Šiame leidime nėra vaizdų ištrynimo 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 vykdytojas paskelbia naują indeksą. Fiksuotos užbaigimo trukmės garantijos nėra.

• Paskelbti produktai patenka ir į produktų paiešką, ir į žinias, kurias naudoja SiteChat pokalbiai.
• Juodraštiniai ir archyvuoti produktai neįtraukiami į kitą perkūrimą.
• Jei indeksavimas nebuvo suplanuotas (index_status: "request_failed"), pakartokite paketą tiems produktams, kurie jau buvo sėkmingai išsaugoti.

Kokios klaidos galimos?

Slapti raktai nustoja galioti po 90 dienų. Prieš galiojimo pabaigą sukurkite pakaitinį raktą skiltyje Settings → Store owner API secret ir atšaukite visus slaptus 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 dėl integracijos, susisiekite su Shoply AI.