Hur du laddar upp din katalog för SiteChat

Om du använder SiteChat på din egen webbplats (inte en Shopify-butik) kan du skicka strukturerade produktposter till Shoply så att kunder kan hitta dem i SiteChat-chatt och produktsökning.

Dessa endpoints använder samma Settings → Store owner API secret som resten av Shoply Merchant API, och adminsidan Product Catalog i SiteChat kan anropa dem med din inloggade admins åtkomsttoken. Shopify-butiker fortsätter att synkronisera katalogdata via Shopify; dessa uppladdningsvägar är endast tillgängliga för SiteChat-konton som inte redan synkroniserar en Magento-katalog.

I SiteChat-admin öppnar Product Catalog ett område i Shopify-stil med Products, Collections och Inventory. Du kan lägga till eller redigera produkter, importera CSV/Excel, gruppera produkter i manuella kollektioner och justera lagersaldon.

Vilka API:er finns tillgängliga?

När produkter sparas framgångsrikt ber Shoply om att bygga om butiksindexet. Tills den ombyggnaden är klar rapporterar svar index_status: "pending". Publicerade produkter visas därefter både i produktindexet och i den kunskap som används av SiteChat-chatten.

Vem kan använda dessa API:er?

• Din butik måste vara ett SiteChat-konto (app_platform är SiteChat).
• Shopify-butiksnycklar (inklusive alla *.myshopify.com-domäner) nekas.
• Autentisering måste använda antingen en giltig API-hemlighet för butiksägare eller en åtkomsttoken för SiteChat-admin för exakt den store_key som anges i begäran.
• Shopify Admin API-tokenar kan inte anropa dessa vägar.

Skapa eller rotera ägarhemligheten på samma sätt som för andra Merchant API-integrationer: Hur du använder Shoply Merchant API. I SiteChats adminpanel öppnar du Product Catalog för att hantera produkter, kollektioner och lager — eller importera en CSV- eller Excel-fil — utan att själv hantera hemligheten.

Hur fungerar autentisering?

Från en serveranslutning

Anropa API:et från en betrodd backend över HTTPS. Lägg en JSON-sträng i Authorization-headern:

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

store_owner_api_secrete är det offentliga fältnamnet, inklusive den historiska stavningen. store_owner_api_secret accepteras också. Detta är inte en Bearer-token.

Från SiteChat-admin

Sidan Product Catalog skickar i stället din inloggade adminsession:

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

access_token accepteras som ett alias för admin_auth_token.

Frågeparametern store_key måste matcha headern. Förvara ägarhemligheter endast i serverbaserade miljövariabler — aldrig i ett storefront-skript, en URL eller ett publikt kodrepo.

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

Hur laddar jag upp 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"}
        }
      ]
    }
  ]
}

Obligatoriska fält och regler

• Obligatoriska produktfält: external_id, title, url, currency, price och available. status är som standard published.
• Valfritt lager: sätt tracks_inventory till true och en icke-negativ quantity på produkten eller varianten. Shoply härleder då tillgänglighet från lagerstatus (quantity > 0) och lagrar total_inventory för adminlistor.
• source namnger kataloganslutningen (inte nödvändigtvis en plattform). Använd ett stabilt namn som woocommerce-main. Tillåtna tecken: gemena bokstäver, siffror, understreck och bindestreck; upp till 64 tecken. Produkter som skapas via formulär i admin använder som standard källan admin.
• Produktidentitet är kombinationen av butik, källa och externt ID. Batch- och enskilda POST-upserts är fullständiga ersättningar, inte patchar: utelämnade valfria fält rensas. Använd PATCH för partiella uppdateringar.
• Batchar innehåller 1–50 produkter och högst 2 000 000 byte i begäran. Varje produkts validerade JSON är begränsad till 128 000 byte, med högst 250 varianter.
• Föredra decimala strängar för priser. Valuta är en trebokstavskod i versaler.
• Produkt- och bild-URL:er måste vara HTTP(S). Importen hämtar inte dessa URL:er åt dig.
• Använd publika metafields för sökbara produktspecifikationer (SiteChats motsvarighet till Shopifys produktmetafält). Värden måste vara vanliga strängar. Äldre attributes accepteras som alias. Privat produkt-metadata stöds inte längre.
• Produkter med draft och archived tas inte med i nästa publicerade index. Slutsålda publicerade produkter förblir indexerade med tillgänglighetsinformation kopplad.
• Manuella kollektioner lagrar en titel, beskrivning, status och en lista över produktmedlemskap (source + external_id). Smarta/reglerbaserade kollektioner stöds inte i denna version.

Exempel på lyckat svar

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

Shoply validerar hela begäran innan något skrivs. En HTTP 200 kan ändå innehålla vissa failed-resultat med error: "storage_error". Granska varje resultat och försök igen för misslyckade produkter. Om index_status är request_failed lyckades lagringen men indexeringen schemalades inte — försök då igen även för de lagrade produkterna.

Python-exempel

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

Hur verifierar jag en importerad produkt?

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

Använd samma Authorization-header. Svaret innehåller schema_version, updated_at, index_status och den normaliserade product. Saknade poster returnerar HTTP 404.

När bakgrundsindexeraren publicerar en ombyggnad blir status för återläsning per produkt indexed, excluded (för utkast eller arkiverade produkter) eller limit_exceeded. Använd GET /merchant/products/list för adminlistning. Mjukarkivera med DELETE /merchant/products (eller sätt status till archived / draft) för att hålla en produkt utanför nästa publicerade index; det finns ingen hård radering i denna version.

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

Hur uppdaterar jag säkert varianter eller metafält?

För en PATCH som innehåller variants, metafields eller det äldre fältet attributes, läs först produkten med GET. Bygg ändringen från det svaret och inkludera dess toppnivåvärde updated_at som expected_updated_at i PATCH-body. Detta gäller också när du rensar varianter eller metafält.

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 att versionen saknades eller att en annan uppdatering ändrade produkten. Läs den senaste produkten och slå samman dina avsedda ändringar igen innan du försöker på nytt. Koppla inte en ny version till en gammal variantlista: det kan skriva över nyare lagervärden.

Befintliga integrationer som PATCH:ar dessa fält utan en version måste uppdateras. PATCH-begäranden som endast innehåller skalära värden, dedikerade lagerjusteringar och fullständiga ersättningar via POST eller batchimport kräver inte detta fält. Fullständiga ersättningar ersätter fortfarande hela produkten.

Kan jag ladda upp produktbilder?

Ja. Om en bild redan finns tillgänglig på en varaktig publik HTTPS-URL, lägg den URL:en i produktens images-lista eller i en variants image-fält. Publika S3 HTTPS-URL:er fungerar. Råa s3://-sökvägar och kortlivade signerade URL:er gör det inte.

För att låta Shoply hosta filen laddar du upp råa bildbytes från din backend:

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

Skicka råa filbytes, inte JSON, base64 eller multipart-formulärdata. JPEG, PNG och WebP accepteras, upp till 10 MiB och 20 miljoner pixlar. Animerade bilder stöds inte. Shoply konverterar bilden till WebP och tar bort inbäddad 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 returnerar url, content_type, size_bytes, width och height. Att bara ladda upp en bild kopplar den inte till en produkt eller begär indexering. Inkludera den returnerade URL:en i en fullständig produkt och skicka in den igen via /merchant/products/batch.

Samma bild som laddas upp igen för samma konto återanvänder sin URL. En ändrad bild får en ny URL. Det finns ingen endpoint för att radera bilder i denna version.

När visas produkter i chatt och sökning?

Efter en lyckad batchsparning begär Shoply en ombyggnad av bakgrundsindexet. Svar rapporterar index_status: "pending" tills processen publicerar det nya indexet. Det finns ingen fast garanti för slutförandetid.

• Publicerade produkter hamnar både i produktsökningen och i den kunskap som används av SiteChat-chatten.
• Utkast och arkiverade produkter exkluderas vid nästa ombyggnad.
• Om indexering inte schemalades (index_status: "request_failed"), försök igen med batchen för de produkter som redan lagrats korrekt.

Vilka fel bör jag förvänta mig?

Hemligheter upphör att gälla efter 90 dagar. Skapa en ersättning i Settings → Store owner API secret innan utgångsdatumet, och återkalla alla hemligheter du inte längre behöver. Samma hemlighet kan också anropa analys-, konversations- och knowledge-endpoints som dokumenteras i Merchant API-guiden.

För hjälp med en integration, kontakta Shoply AI.