Slik laster du opp katalogen din for SiteChat

Hvis du bruker SiteChat på ditt eget nettsted (ikke en Shopify-butikk), kan du sende strukturerte produktposter til Shoply slik at kunder kan finne dem i SiteChat-chat og produktsøk.

Disse endepunktene bruker den samme Settings → Store owner API secret som resten av Shoply Merchant API, og Product Catalog-siden i SiteChat-admin kan kalle dem med din innloggede admin-tilgangstoken. Shopify-butikker fortsetter å synkronisere katalogdata gjennom Shopify; disse opplastingsrutene er kun tilgjengelige for SiteChat-kontoer som ikke allerede synkroniserer en Magento-katalog.

I SiteChat-admin åpner Product Catalog et område i Shopify-stil med Products, Collections og Inventory. Du kan legge til eller redigere produkter, importere CSV/Excel, gruppere produkter i manuelle samlinger og justere lagerbeholdning.

Hvilke API-er er tilgjengelige?

Vellykkede produktsavinger ber Shoply om å bygge butikkindeksen på nytt. Inntil denne gjenoppbyggingen er ferdig, rapporterer svarene index_status: "pending". Publiserte produkter vises deretter både i produktindeksen og i kunnskapen som brukes av SiteChat-chat.

Hvem kan bruke disse API-ene?

• Butikken din må være en SiteChat-konto (app_platform er SiteChat).
• Shopify-butikk-nøkler (inkludert ethvert *.myshopify.com-domene) blir avvist.
• Autentisering må bruke enten en gyldig API-hemmelighet for butikk-eier eller en SiteChat admin-tilgangstoken for den eksakte store_key i forespørselen.
• Shopify Admin API-tokener kan ikke kalle disse rutene.

Opprett eller roter eier-hemmeligheten på samme måte som andre Merchant API-integrasjoner: Hvordan bruke Shoply Merchant API. I SiteChat-adminkonsollen kan du åpne Product Catalog for å administrere produkter, samlinger og lagerbeholdning—eller importere en CSV- eller Excel-fil—uten å administrere hemmeligheten selv.

Hvordan fungerer autentisering?

Fra en serverkobling

Kall API-et fra en pålitelig backend over HTTPS. Legg en JSON-streng i Authorization-headeren:

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

store_owner_api_secrete er det offentlige feltnavnet, inkludert den historiske stavemåten. store_owner_api_secret godtas også. Dette er ikke et Bearer-token.

Fra SiteChat-admin

Siden Product Catalog sender i stedet den innloggede admin-økten din:

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

access_token godtas som et alias for admin_auth_token.

Spørringsparameteren store_key må samsvare med headeren. Oppbevar eier-hemmeligheter kun i server-side miljøvariabler—aldri i et butikkfront-skript, en URL eller et offentlig repository.

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

Hvordan laster jeg opp produkter?

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

Påkrevde felt og regler

• Påkrevde produktfelt: external_id, title, url, currency, price og available. status er som standard published.
• Valgfri lagerbeholdning: sett tracks_inventory til true og et ikke-negativt quantity på produktet eller varianten. Shoply utleder da tilgjengelighet fra lageret (quantity > 0) og lagrer total_inventory for admin-lister.
• source navngir katalogtilkoblingen (ikke nødvendigvis en plattform). Bruk et stabilt navn som woocommerce-main. Tillatte tegn: små bokstaver, tall, understreker og bindestreker; opptil 64 tegn. Produkter opprettet via skjema i admin får som standard source admin.
• Produktidentitet er kombinasjonen av butikk, source og ekstern ID. Batch- og enkel POST-upserts er fullstendige erstatninger, ikke patcher: utelatte valgfrie felt tømmes. Bruk PATCH for delvise oppdateringer.
• Batcher inneholder 1–50 produkter og maksimalt 2 000 000 forespørselsbytes. Hvert produkts validerte JSON er begrenset til 128 000 bytes, med maksimalt 250 varianter.
• Foretrekk desimalstrenger for priser. Valuta er en kode på tre store bokstaver.
• Produkt- og bilde-URL-er må være HTTP(S). Importen henter ikke disse URL-ene for deg.
• Bruk offentlige metafields for søkbare produktspesifikasjoner (SiteChats analog til Shopifys produkt-metafields). Verdier må være rene strenger. Eldre attributes godtas som et alias. Privat produkt-metadata støttes ikke lenger.
• draft- og archived-produkter blir utelatt fra neste publiserte indeks. Utsolgte publiserte produkter forblir indeksert med tilgjengelighet vedlagt.
• Manuelle samlinger lagrer en tittel, beskrivelse, status og en liste over produktmedlemskap (source + external_id). Smarte/reglebaserte samlinger støttes ikke i denne utgaven.

Eksempel på vellykket svar

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

Shoply validerer hele forespørselen før skriving. En HTTP 200 kan fortsatt liste noen failed-resultater med error: "storage_error". Kontroller hvert resultat og prøv igjen for mislykkede produkter. Hvis index_status er request_failed, lyktes lagringen, men indeksering ble ikke planlagt—prøv også de lagrede produktene på nytt.

Python-eksempel

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

Hvordan bekrefter jeg et importert produkt?

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

Bruk den samme Authorization-headeren. Svaret inkluderer schema_version, updated_at, index_status og det normaliserte product. Manglende poster returnerer HTTP 404.

Etter at bakgrunnsindeksereren publiserer en gjenoppbygging, blir status ved tilbake-lesing per produkt indexed, excluded (for kladd- eller arkiverte produkter) eller limit_exceeded. Bruk GET /merchant/products/list for admin-listing. Myk-arkiver med DELETE /merchant/products (eller sett status til archived / draft) for å holde et produkt utenfor neste publiserte indeks; det finnes ingen hard-delete i denne utgaven.

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

Hvordan oppdaterer jeg varianter eller metafields på en trygg måte?

For en PATCH som inneholder variants, metafields eller det eldre feltet attributes, les først produktet med GET. Bygg endringen fra dette svaret og inkluder toppnivåverdien updated_at som expected_updated_at i PATCH-bodyen. Dette gjelder også når du tømmer varianter eller 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 betyr at versjonen manglet eller at en annen oppdatering endret produktet. Les det nyeste produktet og slå sammen de ønskede endringene dine på nytt før du prøver igjen. Ikke legg ved en ny versjon til en gammel variantliste: det kan overskrive nyere lagerverdier.

Eksisterende integrasjoner som PATCH-er disse feltene uten en versjon må oppdateres. PATCH-forespørsler kun med skalare verdier, dedikerte lagerjusteringer og fullstendige erstatninger gjennom POST eller batchimport krever ikke dette feltet. Fullstendige erstatninger erstatter fortsatt hele produktet.

Kan jeg laste opp produktbilder?

Ja. Hvis et bilde allerede er tilgjengelig på en varig offentlig HTTPS-URL, legg den URL-en i produktets images-liste eller i en variants image-felt. Offentlige S3 HTTPS-URL-er fungerer. Rå s3://-stier og kortvarige signerte URL-er gjør det ikke.

For å la Shoply hoste filen, last opp rå bildebytes fra backend-en din:

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

Send rå filbytes, ikke JSON, base64 eller multipart-skjemadata. JPEG, PNG og WebP godtas, opptil 10 MiB og 20 millioner piksler. Animerte bilder støttes ikke. Shoply konverterer bildet til WebP og fjerner innebygd metadata.

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 returnerer url, content_type, size_bytes, width og height. Å laste opp et bilde alene knytter det ikke til et produkt eller ber om indeksering. Inkluder den returnerte URL-en i et fullstendig produkt og send det på nytt gjennom /merchant/products/batch.

Det samme bildet som lastes opp igjen for samme konto gjenbruker URL-en sin. Et endret bilde får en ny URL. Det finnes ikke noe endepunkt for sletting av bilder i denne utgaven.

Når vises produkter i chat og søk?

Etter en vellykket batchlagring ber Shoply om en gjenoppbygging av bakgrunnsindeksen. Svar rapporterer index_status: "pending" inntil arbeideren publiserer den nye indeksen. Det finnes ingen fast garanti for ferdigstillelsestid.

• Publiserte produkter går inn i både produktsøk og kunnskapen som brukes av SiteChat-chat.
• Kladd- og arkiverte produkter blir ekskludert ved neste gjenoppbygging.
• Hvis indeksering ikke ble planlagt (index_status: "request_failed"), prøv batchen på nytt for produktene som allerede ble lagret.

Hvilke feil bør jeg forvente?

Hemmeligheter utløper etter 90 dager. Opprett en erstatning i Settings → Store owner API secret før utløp, og tilbakekall enhver hemmelighet du ikke lenger trenger. Den samme hemmeligheten kan også kalle analyse-, samtale- og kunnskapsendepunkter dokumentert i Merchant API-guiden.

For hjelp med en integrasjon, kontakt Shoply AI.