Jak przesłać swój katalog do SiteChat

Jeśli używasz SiteChat na własnej stronie internetowej (a nie w sklepie Shopify), możesz wysyłać uporządkowane rekordy produktów do Shoply, aby klienci mogli je znaleźć w czacie SiteChat i w wyszukiwaniu produktów.

Te endpointy używają tego samego Settings → Store owner API secret co pozostała część Shoply Merchant API, a strona Product Catalog w panelu administracyjnym SiteChat może je wywoływać przy użyciu tokena dostępu zalogowanego administratora. Sklepy Shopify nadal synchronizują dane katalogowe przez Shopify; te trasy przesyłania są dostępne wyłącznie dla kont SiteChat, które nie synchronizują już katalogu Magento.

W panelu administracyjnym SiteChat sekcja Product Catalog otwiera obszar w stylu Shopify z zakładkami Products, Collections i Inventory. Możesz dodawać lub edytować produkty, importować pliki CSV/Excel, grupować produkty w ręczne kolekcje i dostosowywać stany magazynowe.

Jakie API są dostępne?

Pomyślne zapisy produktów powodują, że Shoply rozpoczyna przebudowę indeksu sklepu. Dopóki ta przebudowa się nie zakończy, odpowiedzi raportują index_status: "pending". Opublikowane produkty pojawiają się wtedy zarówno w indeksie produktów, jak i w bazie wiedzy używanej przez czat SiteChat.

Kto może korzystać z tych API?

• Twój sklep musi być kontem SiteChat (app_platform to SiteChat).
• Klucze sklepu Shopify (w tym dowolna domena *.myshopify.com) są odrzucane.
• Uwierzytelnianie musi używać albo prawidłowego tajnego klucza API właściciela sklepu, albo tokena dostępu administratora SiteChat dla dokładnie tego store_key, który znajduje się w żądaniu.
• Tokeny Shopify Admin API nie mogą wywoływać tych tras.

Utwórz lub zmień owner secret w ten sam sposób, co w innych integracjach Merchant API: How to Use the Shoply Merchant API. W konsoli administracyjnej SiteChat otwórz Product Catalog, aby zarządzać produktami, kolekcjami i stanami magazynowymi — albo importować plik CSV lub Excel — bez samodzielnego zarządzania sekretem.

Jak działa uwierzytelnianie?

Z konektora serwerowego

Wywołuj API z zaufanego backendu przez HTTPS. Umieść ciąg JSON w nagłówku Authorization:

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

store_owner_api_secrete to publiczna nazwa pola, łącznie z historyczną pisownią. store_owner_api_secret również jest akceptowane. To nie jest token Bearer.

Z panelu administracyjnego SiteChat

Strona Product Catalog zamiast tego wysyła sesję zalogowanego administratora:

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

access_token jest akceptowany jako alias dla admin_auth_token.

Parametr zapytania store_key musi odpowiadać nagłówkowi. Przechowuj owner secret wyłącznie w zmiennych środowiskowych po stronie serwera — nigdy w skrypcie storefrontu, adresie URL ani publicznym repozytorium.

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

Jak przesłać produkty?

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

Wymagane pola i zasady

• Wymagane pola produktu: external_id, title, url, currency, price i available. status domyślnie ma wartość published.
• Opcjonalny stan magazynowy: ustaw tracks_inventory na true oraz nieujemne quantity dla produktu lub wariantu. Shoply wyprowadzi wtedy dostępność ze stanu magazynowego (quantity > 0) i zapisze total_inventory dla list administracyjnych.
• source określa połączenie katalogu (niekoniecznie platformę). Używaj stabilnej nazwy, takiej jak woocommerce-main. Dozwolone znaki: małe litery, cyfry, podkreślenia i myślniki; maksymalnie 64 znaki. Produkty tworzone przez formularz w panelu administracyjnym domyślnie mają source admin.
• Tożsamość produktu to połączenie sklepu, source i external ID. Batch oraz pojedyncze upserty POST są pełnymi zastąpieniami, a nie łatkami: pominięte pola opcjonalne są czyszczone. Użyj PATCH do częściowych aktualizacji.
• Partie zawierają od 1 do 50 produktów i maksymalnie 2 000 000 bajtów żądania. Zweryfikowany JSON każdego produktu jest ograniczony do 128 000 bajtów, przy maksymalnie 250 wariantach.
• Dla cen preferowane są dziesiętne ciągi znaków. Waluta to trzyliterowy kod zapisany wielkimi literami.
• Adresy URL produktów i obrazów muszą być HTTP(S). Import nie pobiera tych adresów URL za Ciebie.
• Używaj publicznych metafields dla wyszukiwalnych specyfikacji produktów (odpowiednik metafields produktów Shopify w SiteChat). Wartości muszą być zwykłymi ciągami znaków. Starsze attributes jest akceptowane jako alias. Prywatne produktowe metadata nie jest już obsługiwane.
• Produkty draft i archived są pomijane w kolejnym opublikowanym indeksie. Wyprzedane opublikowane produkty pozostają zaindeksowane z dołączoną informacją o dostępności.
• Ręczne kolekcje przechowują tytuł, opis, status oraz listę powiązań produktów (source + external_id). Kolekcje inteligentne/oparte na regułach nie są obsługiwane w tej wersji.

Przykładowa odpowiedź powodzenia

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

Shoply weryfikuje całe żądanie przed zapisem. HTTP 200 nadal może zawierać niektóre wyniki failed z error: "storage_error". Sprawdź każdy wynik i ponów próbę dla nieudanych produktów. Jeśli index_status ma wartość request_failed, zapis się powiódł, ale indeksowanie nie zostało zaplanowane — ponów również próbę dla już zapisanych produktów.

Przykład w Pythonie

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

Jak zweryfikować zaimportowany produkt?

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

Użyj tego samego nagłówka Authorization. Odpowiedź zawiera schema_version, updated_at, index_status oraz znormalizowany product. Brakujące rekordy zwracają HTTP 404.

Po tym, jak indeksator działający w tle opublikuje przebudowę, status odczytu pojedynczego produktu przyjmuje wartość indexed, excluded (dla produktów draft lub archived) albo limit_exceeded. Użyj GET /merchant/products/list do list administracyjnych. Miękko archiwizuj przez DELETE /merchant/products (lub ustaw status na archived / draft), aby produkt nie trafił do kolejnego opublikowanego indeksu; w tej wersji nie ma twardego usuwania.

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

Czy mogę przesyłać obrazy produktów?

Tak. Jeśli obraz jest już dostępny pod trwałym publicznym adresem HTTPS, umieść ten adres URL na liście images produktu lub w polu image wariantu. Publiczne adresy HTTPS S3 działają. Surowe ścieżki s3:// i krótkotrwałe podpisane adresy URL nie działają.

Aby Shoply hostowało plik, prześlij surowe bajty obrazu ze swojego backendu:

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

Wyślij surowe bajty pliku, a nie JSON, base64 ani dane formularza multipart. Akceptowane są JPEG, PNG i WebP, do 10 MiB i 20 milionów pikseli. Obrazy animowane nie są obsługiwane. Shoply konwertuje obraz do WebP i usuwa osadzone metadane.

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 zwraca url, content_type, size_bytes, width i height. Samo przesłanie obrazu nie przypisuje go do produktu ani nie uruchamia indeksowania. Umieść zwrócony adres URL w kompletnym produkcie i prześlij go ponownie przez /merchant/products/batch.

Ponowne przesłanie tego samego obrazu dla tego samego konta powoduje użycie tego samego adresu URL. Zmieniony obraz otrzymuje nowy adres URL. W tej wersji nie ma endpointu do usuwania obrazów.

Kiedy produkty pojawiają się w czacie i wyszukiwaniu?

Po pomyślnym zapisaniu partii Shoply zleca przebudowę indeksu w tle. Odpowiedzi raportują index_status: "pending", dopóki worker nie opublikuje nowego indeksu. Nie ma gwarancji stałego czasu ukończenia.

• Opublikowane produkty trafiają zarówno do wyszukiwania produktów, jak i do bazy wiedzy używanej przez czat SiteChat.
• Produkty draft i archived są wykluczane przy kolejnej przebudowie.
• Jeśli indeksowanie nie zostało zaplanowane (index_status: "request_failed"), ponów partię dla produktów, które zostały już pomyślnie zapisane.

Jakich błędów należy się spodziewać?

Sekrety wygasają po 90 dniach. Utwórz zamiennik w Settings → Store owner API secret przed wygaśnięciem i cofnij każdy secret, którego już nie potrzebujesz. Ten sam secret może również wywoływać endpointy analityki, konwersacji i wiedzy udokumentowane w przewodniku Merchant API.

Aby uzyskać pomoc przy integracji, skontaktuj się z Shoply AI.