Sådan uploader du dit katalog til SiteChat

Hvis du bruger SiteChat på dit eget website (ikke en Shopify-butik), kan du sende strukturerede produktposter til Shoply, så kunder kan finde dem i SiteChat-chat og produktsøgning.

Disse endpoints bruger den samme Indstillinger → Butiksejers API-hemmelighed som resten af Shoply Merchant API, og SiteChat-adminsiden Product Catalog kan kalde dem med din admin-adgangstoken, når du er logget ind. Shopify-butikker fortsætter med at synkronisere katalogdata gennem Shopify; disse upload-ruter er kun tilgængelige for SiteChat-konti, som ikke allerede synkroniserer et Magento-katalog.

I SiteChat-admin åbner Product Catalog et område i Shopify-stil med Products, Collections og Inventory. Du kan tilføje eller redigere produkter, importere CSV/Excel, gruppere produkter i manuelle collections og justere lagerantal.

Hvilke API’er er tilgængelige?

Vellykkede produktsaves beder Shoply om at genopbygge butikkens indeks. Indtil den genopbygning er færdig, rapporterer svar index_status: "pending". Publicerede produkter vises derefter både i produktindekset og i den viden, som bruges af SiteChat-chat.

Hvem kan bruge disse API’er?

• Din butik skal være en SiteChat-konto (app_platform er SiteChat).
• Shopify-butiknøgler (inklusive ethvert *.myshopify.com-domæne) afvises.
• Autentificering skal bruge enten en gyldig butiksejers API-hemmelighed eller en SiteChat-admin-adgangstoken for den præcise store_key i requesten.
• Shopify Admin API-tokens kan ikke kalde disse ruter.

Opret eller rotér ejers hemmelighed på samme måde som andre Merchant API-integrationer: Sådan bruger du Shoply Merchant API. I SiteChat-admin-konsollen kan du åbne Product Catalog for at administrere produkter, collections og lager — eller importere en CSV- eller Excel-fil — uden selv at håndtere hemmeligheden.

Hvordan fungerer autentificering?

Fra en serverconnector

Kald API’et fra en betroet backend over HTTPS. Læg 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 feltnavn, inklusive den historiske stavemåde. store_owner_api_secret accepteres også. Dette er ikke en Bearer-token.

Fra SiteChat-admin

Siden Product Catalog sender i stedet din admin-session, når du er logget ind:

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

access_token accepteres som et alias for admin_auth_token.

Query-parameteren store_key skal matche headeren. Opbevar kun ejers hemmeligheder i miljøvariabler på serversiden — aldrig i et storefront-script, en URL eller et offentligt repository.

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

Hvordan uploader jeg 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åkrævede felter og regler

• Påkrævede produktfelter: external_id, title, url, currency, price og available. status er som standard published.
• Valgfrit lager: sæt tracks_inventory til true og et ikke-negativt quantity på produktet eller varianten. Shoply udleder derefter tilgængelighed fra lageret (quantity > 0) og gemmer total_inventory til admin-lister.
• source navngiver katalogforbindelsen (ikke nødvendigvis en platform). Brug et stabilt navn som woocommerce-main. Tilladte tegn: små bogstaver, tal, underscores og bindestreger; op til 64 tegn. Produkter oprettet via formular i admin bruger som standard source admin.
• Produktidentitet er kombinationen af butik, source og external ID. Batch- og enkeltstående POST-upserts er fulde erstatninger, ikke patches: udeladte valgfrie felter ryddes. Brug PATCH til delvise opdateringer.
• Batches indeholder 1–50 produkter og højst 2.000.000 request-bytes. Hvert produkts validerede JSON er begrænset til 128.000 bytes med højst 250 varianter.
• Foretræk decimalstrenge til priser. Valuta er en tres bogstavers kode med store bogstaver.
• Produkt- og billed-URL’er skal være HTTP(S). Import henter ikke disse URL’er for dig.
• Brug offentlige metafields til søgbare produktspecifikationer (SiteChats pendant til Shopifys produkt-metafields). Værdier skal være almindelige strenge. Ældre attributes accepteres som et alias. Privat produkt-metadata understøttes ikke længere.
• draft- og archived-produkter udelades fra det næste publicerede indeks. Udsolgte publicerede produkter forbliver indekseret med tilgængelighed knyttet til dem.
• Manuelle collections gemmer en titel, beskrivelse, status og en liste over produktmedlemskaber (source + external_id). Smarte/regler-baserede collections understøttes ikke i denne udgivelse.

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 requesten, før der skrives noget. En HTTP 200 kan stadig indeholde nogle failed-resultater med error: "storage_error". Gennemgå hvert resultat, og prøv igen for mislykkede produkter. Hvis index_status er request_failed, lykkedes lagringen, men indeksering blev ikke planlagt — prøv også de gemte produkter igen.

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 verificerer jeg et importeret produkt?

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

Brug den samme Authorization-header. Svaret inkluderer schema_version, updated_at, index_status og det normaliserede product. Manglende poster returnerer HTTP 404.

Efter at baggrundsindekseringen publicerer en genopbygning, bliver status ved læsning af det enkelte produkt indexed, excluded (for draft- eller archived-produkter) eller limit_exceeded. Brug GET /merchant/products/list til admin-lister. Soft-arkivér med DELETE /merchant/products (eller sæt status til archived / draft) for at holde et produkt ude af det næste publicerede indeks; der findes ingen hard-delete i denne udgivelse.

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 uploade produktbilleder?

Ja. Hvis et billede allerede er tilgængeligt på en varig offentlig HTTPS-URL, skal du lægge den URL i produktets images-liste eller i en variants image-felt. Offentlige S3 HTTPS-URL’er virker. Rå s3://-stier og kortlivede signerede URL’er gør ikke.

For at lade Shoply hoste filen skal du uploade rå billedbytes fra din backend:

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 form data. JPEG, PNG og WebP accepteres, op til 10 MiB og 20 millioner pixels. Animerede billeder understøttes ikke. Shoply konverterer billedet til WebP og fjerner indlejrede 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. Upload af et billede alene knytter det ikke til et produkt eller anmoder om indeksering. Inkludér den returnerede URL i et komplet produkt, og indsend det igen via /merchant/products/batch.

Det samme billede, der uploades igen for den samme konto, genbruger sin URL. Et ændret billede får en ny URL. Der findes ikke et image-delete-endpoint i denne udgivelse.

Hvornår vises produkter i chat og søgning?

Efter et vellykket batch-save anmoder Shoply om en genopbygning af baggrundsindekset. Svar rapporterer index_status: "pending", indtil worker’en publicerer det nye indeks. Der er ingen fast garanti for færdiggørelsestid.

• Publicerede produkter kommer med i både produktsøgning og den viden, som bruges af SiteChat-chat.
• Draft- og archived-produkter udelukkes ved næste genopbygning.
• Hvis indeksering ikke blev planlagt (index_status: "request_failed"), skal du prøve batchen igen for de produkter, der allerede blev lagret korrekt.

Hvilke fejl skal jeg forvente?

Hemmeligheder udløber efter 90 dage. Opret en erstatning i Indstillinger → Butiksejers API-hemmelighed før udløb, og tilbagekald enhver hemmelighed, du ikke længere har brug for. Den samme hemmelighed kan også kalde analytics-, conversation- og knowledge-endpoints dokumenteret i Merchant API-guiden.

Hvis du har brug for hjælp til en integration, kan du kontakte Shoply AI.