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 Innstillinger → Butikk-eierens API-hemmelighet som resten av Shoply Merchant API, og SiteChat-adminsiden Produktkatalog kan kalle dem med ditt innloggede admin-tilgangstoken. Shopify-butikker fortsetter å synkronisere katalogdata gjennom Shopify; disse opplastingsrutene er bare tilgjengelige for SiteChat-kontoer som ikke allerede synkroniserer en Magento-katalog.

I SiteChat-admin åpner Produktkatalog et område i Shopify-stil med Produkter, Samlinger og Lagerbeholdning. Du kan legge til eller redigere produkter, importere CSV/Excel, gruppere produkter i manuelle samlinger og justere lagerantall.

Hvilke API-er er tilgjengelige?

Vellykkede produktsavinger ber Shoply om å bygge butikkindeksen på nytt. Inntil den 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-butikknøkler (inkludert ethvert *.myshopify.com-domene) avvises.
• Autentisering må bruke enten en gyldig butikk-eier-API-hemmelighet eller et SiteChat admin-tilgangstoken for nøyaktig den store_key som brukes 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 åpner du Produktkatalog 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 Produktkatalog sender i stedet din innloggede admin-økt:

{
  "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 repositorium.

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

Obligatoriske felt og regler

• Obligatoriske produktfelt: external_id, title, url, currency, price og available. status har standardverdien published.
• Valgfri lagerbeholdning: sett tracks_inventory til true og et ikke-negativt quantity på produktet eller varianten. Shoply utleder da tilgjengelighet fra lager (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 bruker som standard kilden admin.
• Produktidentitet er kombinasjonen av butikk, kilde 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ørselsbyte. Hvert produkts validerte JSON er begrenset til 128 000 byte, med maksimalt 250 varianter.
• Foretrekk desimalstrenger for priser. Valuta er en trebokstavers kode med store bokstaver.
• Produkt- og bilde-URL-er må være HTTP(S). Import henter ikke disse URL-ene for deg.
• Bruk offentlige metafields for søkbare produktspesifikasjoner (SiteChats analog til Shopifys produkt-metafields). Verdier må være enkle strenger. Eldre attributes godtas som et alias. Privat produkt-metadata støttes ikke lenger.
• draft- og archived-produkter utelates 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/regler-baserte samlinger støttes ikke i denne utgivelsen.

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". Inspiser hvert resultat og prøv mislykkede produkter på nytt. 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 verifiserer 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 for 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 ute av neste publiserte indeks; det finnes ingen hard-delete i denne utgivelsen.

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

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 kortlivede signerte URL-er gjør det ikke.

For å la Shoply hoste filen, last opp rå bildebiter fra backenden din:

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

Send rå filbiter, 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 inn 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 utgivelsen.

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

Etter en vellykket batch-lagring ber Shoply om en gjenoppbygging av bakgrunnsindeksen. Svar rapporterer index_status: "pending" inntil arbeidsprosessen publiserer den nye indeksen. Det finnes ingen fast garanti for fullføringstid.

• Publiserte produkter kommer inn både i produktsøk og i kunnskapen som brukes av SiteChat-chat.
• Kladd- og arkiverte produkter ekskluderes 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 Innstillinger → Butikk-eierens API-hemmelighet 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.