Kuinka ladata tuoteluettelosi SiteChatia varten

Jos käytät SiteChatia omalla verkkosivustollasi (et Shopify-kaupassa), voit lähettää jäsenneltyjä tuotetietueita Shoplyyn, jotta ostajat voivat löytää ne SiteChat-chatissa ja tuotehaussa.

Nämä päätepisteet käyttävät samaa Settings → Store owner API secret -asetusta kuin muu Shoply Merchant API, ja SiteChatin ylläpidon Product Catalog -sivu voi kutsua niitä sisäänkirjautuneen ylläpitäjän käyttöoikeustunnuksella. Shopify-kaupat synkronoivat edelleen tuoteluettelotiedot Shopifyn kautta; nämä latausreitit ovat käytettävissä vain SiteChat-tileille, jotka eivät jo synkronoi Magento-tuoteluetteloa.

SiteChatin ylläpidossa Product Catalog avaa Shopify-tyylisen alueen, jossa on Products, Collections ja Inventory. Voit lisätä tai muokata tuotteita, tuoda CSV-/Excel-tiedostoja, ryhmitellä tuotteita manuaalisiin kokoelmiin ja säätää varastomääriä.

Mitä API-rajapintoja on saatavilla?

Onnistuneet tuotetallennukset pyytävät Shoplya rakentamaan kaupan indeksin uudelleen. Kunnes uudelleenrakennus valmistuu, vastaukset ilmoittavat index_status: "pending". Julkaistut tuotteet näkyvät sitten sekä tuoteindeksissä että tiedossa, jota SiteChat-chat käyttää.

Kuka voi käyttää näitä API-rajapintoja?

• Kauppasi on oltava SiteChat-tili (app_platform on SiteChat).
• Shopify-kauppojen avaimet (mukaan lukien kaikki *.myshopify.com-verkkotunnukset) hylätään.
• Todennuksen on käytettävä joko kelvollista kaupan omistajan API-salaisuutta tai SiteChatin ylläpitäjän käyttöoikeustunnusta täsmälleen pyynnön store_key-arvolle.
• Shopify Admin API -tunnukset eivät voi kutsua näitä reittejä.

Luo tai vaihda omistajan salaisuus samalla tavalla kuin muutkin Merchant API -integraatiot: Kuinka käyttää Shoply Merchant API:a. SiteChatin ylläpitokonsolissa avaa Product Catalog hallitaksesi tuotteita, kokoelmia ja varastoa — tai tuodaksesi CSV- tai Excel-tiedoston — ilman, että hallitset salaisuutta itse.

Miten todennus toimii?

Palvelinyhdistimestä

Kutsu API:a luotetusta taustajärjestelmästä HTTPS:n kautta. Lisää Authorization-otsakkeeseen JSON-merkkijono:

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

store_owner_api_secrete on julkinen kenttänimi, mukaan lukien historiallinen kirjoitusasu. store_owner_api_secret hyväksytään myös. Tämä ei ole Bearer-tunnus.

SiteChatin ylläpidosta

Product Catalog -sivu lähettää sen sijaan sisäänkirjautuneen ylläpitäjäistuntosi:

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

access_token hyväksytään admin_auth_token-kentän aliaksena.

store_key-kyselyparametrin on vastattava otsaketta. Säilytä omistajan salaisuudet vain palvelinpuolen ympäristömuuttujissa — ei koskaan kaupan skriptissä, URL-osoitteessa tai julkisessa repositoriossa.

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

Kuinka lataan tuotteita?

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

Pakolliset kentät ja säännöt

• Pakolliset tuotekentät: external_id, title, url, currency, price ja available. status on oletuksena published.
• Valinnainen varasto: aseta tracks_inventory arvoksi true ja ei-negatiivinen quantity tuotteelle tai variantille. Tällöin Shoply johtaa saatavuuden varastosta (quantity > 0) ja tallentaa total_inventory-arvon ylläpitoluetteloita varten.
• source nimeää tuoteluetteloyhteyden (ei välttämättä alustaa). Käytä vakaata nimeä kuten woocommerce-main. Sallitut merkit: pienet kirjaimet, numerot, alaviivat ja yhdysmerkit; enintään 64 merkkiä. Ylläpidossa lomakkeella luotujen tuotteiden oletuslähde on admin.
• Tuotteen identiteetti on kaupan, lähteen ja ulkoisen tunnisteen yhdistelmä. Erä- ja yksittäiset POST-upsertit ovat täysiä korvauksia, eivät paikkauksia: pois jätetyt valinnaiset kentät tyhjennetään. Käytä PATCH-menetelmää osittaisiin päivityksiin.
• Erät sisältävät 1–50 tuotetta ja enintään 2 000 000 pyyntötavua. Kunkin tuotteen validoitu JSON on rajoitettu 128 000 tavuun, ja variantteja voi olla enintään 250.
• Suosi desimaalimuotoisia merkkijonoja hinnoille. Valuutta on kolmikirjaiminen isoilla kirjaimilla kirjoitettu koodi.
• Tuote- ja kuva-URL-osoitteiden on oltava HTTP(S)-muotoisia. Tuonti ei nouda näitä URL-osoitteita puolestasi.
• Käytä julkisia metafields-kenttiä haettaville tuotemäärityksille (SiteChatin vastine Shopifyn tuotemetafieldeille). Arvojen on oltava tavallisia merkkijonoja. Vanha attributes hyväksytään aliaksena. Yksityistä tuotteen metadata-kenttää ei enää tueta.
• draft- ja archived-tuotteet jätetään pois seuraavasta julkaistusta indeksistä. Loppuunmyydyt julkaistut tuotteet pysyvät indeksoituina saatavuustiedon kanssa.
• Manuaaliset kokoelmat tallentavat otsikon, kuvauksen, tilan ja listan tuotejäsenyyksistä (source + external_id). Älykkäitä/sääntöpohjaisia kokoelmia ei tueta tässä julkaisussa.

Esimerkki onnistuneesta vastauksesta

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

Shoply validoi koko pyynnön ennen kirjoittamista. HTTP 200 voi silti sisältää joitakin failed-tuloksia, joissa on error: "storage_error". Tarkista jokainen tulos ja yritä epäonnistuneita tuotteita uudelleen. Jos index_status on request_failed, tallennus onnistui, mutta indeksointia ei ajastettu — yritä myös tallennetut tuotteet uudelleen.

Python-esimerkki

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

Kuinka varmistan tuodun tuotteen?

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

Käytä samaa Authorization-otsaketta. Vastaus sisältää schema_version, updated_at, index_status ja normalisoidun product-objektin. Puuttuvat tietueet palauttavat HTTP 404.

Kun taustalla toimiva indeksoija julkaisee uudelleenrakennuksen, tuotekohtainen takaisinlukutila muuttuu arvoon indexed, excluded (luonnos- tai arkistoiduille tuotteille) tai limit_exceeded. Käytä GET /merchant/products/list ylläpitolistaukseen. Pehmeä arkistointi tehdään DELETE /merchant/products -kutsulla (tai asettamalla status arvoon archived / draft), jotta tuote pysyy poissa seuraavasta julkaistusta indeksistä; tässä julkaisussa ei ole kovaa poistoa.

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

Kuinka päivitän variantteja tai metafieldejä turvallisesti?

Jos PATCH sisältää variants-, metafields- tai vanhan attributes-kentän, lue tuote ensin GET-kutsulla. Rakenna muokkaus kyseisestä vastauksesta ja sisällytä sen ylimmän tason updated_at-arvo PATCH-rungossa kenttään expected_updated_at. Tämä koskee myös varianttien tai metafieldien tyhjentämistä.

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 tarkoittaa, että versio puuttui tai toinen päivitys muutti tuotetta. Lue uusin tuote ja yhdistä aiotut muutoksesi uudelleen ennen uutta yritystä. Älä liitä uutta versiota vanhaan varianttiluetteloon: se voisi ylikirjoittaa uudemmat varastoarvot.

Olemassa olevat integraatiot, jotka tekevät PATCH-päivityksiä näihin kenttiin ilman versiota, on päivitettävä. Vain skalaareja sisältävät PATCH-pyynnöt, erilliset varastomuutokset ja täydet korvaukset POST- tai erätuonnin kautta eivät vaadi tätä kenttää. Täydet korvaukset korvaavat silti koko tuotteen.

Voinko ladata tuotekuvia?

Kyllä. Jos kuva on jo saatavilla pysyvässä julkisessa HTTPS-URL-osoitteessa, lisää tuo URL tuotteen images-listaan tai variantin image-kenttään. Julkiset S3 HTTPS -URL-osoitteet toimivat. Raakoja s3://-polkuja ja lyhytikäisiä allekirjoitettuja URL-osoitteita ei hyväksytä.

Jos haluat Shoplyn isännöivän tiedostoa, lataa raaka kuvatavu taustajärjestelmästäsi:

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

Lähetä raakaa tiedostobittiä, älä JSONia, base64:ää tai multipart-lomakedataa. JPEG, PNG ja WebP hyväksytään, enintään 10 MiB ja 20 miljoonaa pikseliä. Animoituja kuvia ei tueta. Shoply muuntaa kuvan WebP-muotoon ja poistaa upotetun metadatan.

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 palauttaa kentät url, content_type, size_bytes, width ja height. Pelkkä kuvan lataaminen ei liitä sitä tuotteeseen eikä pyydä indeksointia. Sisällytä palautettu URL täydelliseen tuotteeseen ja lähetä se uudelleen /merchant/products/batch-reitin kautta.

Jos sama kuva ladataan uudelleen samalle tilille, sen URL käytetään uudelleen. Muuttunut kuva saa uuden URL-osoitteen. Tässä julkaisussa ei ole kuvan poistopäätepistettä.

Milloin tuotteet näkyvät chatissa ja haussa?

Onnistuneen erätallennuksen jälkeen Shoply pyytää taustalla tapahtuvaa indeksin uudelleenrakennusta. Vastaukset ilmoittavat index_status: "pending", kunnes työntekijä julkaisee uuden indeksin. Valmistumisajalle ei ole kiinteää takuuta.

• Julkaistut tuotteet tulevat sekä tuotehakuun että tietoon, jota SiteChat-chat käyttää.
• Luonnos- ja arkistoidut tuotteet suljetaan pois seuraavassa uudelleenrakennuksessa.
• Jos indeksointia ei ajastettu (index_status: "request_failed"), yritä eräajo uudelleen tuotteille, jotka tallentuivat jo onnistuneesti.

Mitä virheitä minun pitäisi odottaa?

Salaisuudet vanhenevat 90 päivän kuluttua. Luo korvaava salaisuus kohdassa Settings → Store owner API secret ennen vanhenemista ja peruuta kaikki salaisuudet, joita et enää tarvitse. Samalla salaisuudella voi myös kutsua analytiikka-, keskustelu- ja tietopäätepisteitä, jotka on dokumentoitu Merchant API -oppaassa.

Jos tarvitset apua integraation kanssa, ota yhteyttä Shoply AI:hin.