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 Settings → Store owner API secret som resten af Shoply Merchant API, og SiteChat-adminsiden Product Catalog kan kalde dem med dit admin-adgangstoken, når du er logget ind. Shopify-butikker fortsætter med at synkronisere katalogdata gennem Shopify; disse uploadruter er kun tilgængelige for SiteChat-konti, der 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, der 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.
• Godkendelse skal bruge enten en gyldig butiksejer-API-hemmelighed eller et SiteChat admin-adgangstoken for den præcise store_key i anmodningen.
• Shopify Admin API-tokens kan ikke kalde disse ruter.

Opret eller roter owner secret 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 inventory — eller importere en CSV- eller Excel-fil — uden selv at administrere hemmeligheden.

Hvordan fungerer godkendelse?

Fra en serverconnector

Kald API’et fra en betroet backend over HTTPS. Sæt 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 et Bearer-token.

Fra SiteChat-admin

Siden Product Catalog sender i stedet din indloggede admin-session:

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

access_token accepteres som alias for admin_auth_token.

Query-parameteren store_key skal matche headeren. Opbevar kun owner secrets i server-side miljøvariabler — 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 enkelt-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 decimale strenge til priser. Valuta er en trebogstavs 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 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 tilknyttet tilgængelighed.
• Manuelle collections gemmer en titel, beskrivelse, status og en liste over produktmedlemskaber (source + external_id). Smart-/regelbaserede 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 anmodningen før skrivning. En HTTP 200 kan stadig indeholde nogle failed-resultater med error: "storage_error". Gennemgå hvert resultat, og prøv de fejlede produkter igen. Hvis index_status er request_failed, lykkedes lagringen, men indeksering blev ikke planlagt — prøv også de lagrede 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 indeholder schema_version, updated_at, index_status og det normaliserede product. Manglende poster returnerer HTTP 404.

Når baggrundsindeksereren publicerer en genopbygning, bliver status ved tilbage-læsning pr. 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 er 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"])

Hvordan opdaterer jeg varianter eller metafields sikkert?

For en PATCH, der indeholder variants, metafields eller det ældre felt attributes, skal du først læse produktet med GET. Byg redigeringen ud fra det svar, og inkluder dets top-level updated_at-værdi som expected_updated_at i PATCH-bodyen. Dette gælder også, når varianter eller metafields ryddes.

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 betyder, at versionen manglede, eller at en anden opdatering ændrede produktet. Læs det nyeste produkt, og sammenflet derefter dine ønskede ændringer igen, før du prøver igen. Tilføj ikke en ny version til en gammel variantliste: det kan overskrive nyere lagerværdier.

Eksisterende integrationer, der PATCH’er disse felter uden en version, skal opdateres. PATCH-anmodninger kun med skalære felter, dedikerede lagerjusteringer og fulde erstatninger via POST eller batchimport kræver ikke dette felt. Fuld erstatning erstatter stadig hele produktet.

Kan jeg uploade produktbilleder?

Ja. Hvis et billede allerede er tilgængeligt på en varig offentlig HTTPS-URL, skal du angive 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 og anmoder ikke 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 til den samme konto, genbruger sin URL. Et ændret billede får en ny URL. Der er ikke noget endpoint til sletning af billeder i denne udgivelse.

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

Efter en 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, der bruges af SiteChat-chat.
• Draft- og archived-produkter udelades 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?

Secrets udløber efter 90 dage. Opret en erstatning i Settings → Store owner API secret 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.