Как да качите каталога си за SiteChat

Ако използвате SiteChat на собствен уебсайт (не в Shopify магазин), можете да изпращате структурирани продуктови записи към Shoply, така че купувачите да могат да ги намират в чата на SiteChat и в продуктовото търсене.

Тези крайни точки използват същата Settings → Store owner API secret като останалата част от Shoply Merchant API, а страницата Product Catalog в админ панела на SiteChat може да ги извиква с вашия токен за достъп на влязъл администратор. Shopify магазините продължават да синхронизират каталожните данни чрез Shopify; тези маршрути за качване са налични само за акаунти в SiteChat, които вече не синхронизират Magento каталог.

В админ панела на SiteChat, Product Catalog отваря зона в стил Shopify с Products, Collections и Inventory. Можете да добавяте или редактирате продукти, да импортирате CSV/Excel, да групирате продукти в ръчни колекции и да коригирате складовите количества.

Какви API-та са налични?

Успешните записвания на продукти карат Shoply да преизгради индекса на магазина. Докато това преизграждане не завърши, отговорите отчитат index_status: "pending". След това публикуваните продукти се появяват както в продуктовия индекс, така и в знанието, използвано от чата на SiteChat.

Кой може да използва тези API-та?

• Вашият магазин трябва да е акаунт в SiteChat (app_platform е SiteChat).
• Ключове за Shopify магазини (включително всеки домейн *.myshopify.com) се отхвърлят.
• Удостоверяването трябва да използва или валидна API тайна на собственика на магазина, или токен за достъп на администратор на SiteChat за точно същия store_key в заявката.
• Токените на Shopify Admin API не могат да извикват тези маршрути.

Създайте или сменете тайната на собственика по същия начин, както при другите интеграции с Merchant API: How to Use the Shoply Merchant API. В админ конзолата на SiteChat отворете Product Catalog, за да управлявате продукти, колекции и наличности — или да импортирате CSV или Excel файл — без сами да управлявате тайната.

Как работи удостоверяването?

От сървърен конектор

Извикайте API-то от доверен бекенд през HTTPS. Поставете JSON низ в заглавката Authorization:

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

store_owner_api_secrete е публичното име на полето, включително историческия правопис. store_owner_api_secret също се приема. Това не е Bearer токен.

От админ панела на SiteChat

Страницата Product Catalog вместо това изпраща вашата администраторска сесия на влязъл потребител:

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

access_token се приема като псевдоним на admin_auth_token.

Параметърът на заявката store_key трябва да съвпада със заглавката. Пазете тайните на собственика само в сървърни променливи на средата — никога в storefront script, URL или публично хранилище.

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

Как да кача продукти?

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

Задължителни полета и правила

• Задължителни полета за продукта: external_id, title, url, currency, price и available. status по подразбиране е published.
• Незадължителна наличност: задайте tracks_inventory на true и неотрицателно quantity на продукта или варианта. След това Shoply извежда наличността от склада (quantity > 0) и съхранява total_inventory за админ списъци.
• source назовава връзката към каталога (не непременно платформа). Използвайте стабилно име като woocommerce-main. Разрешени знаци: малки букви, цифри, долни черти и тирета; до 64 знака. Създадените чрез формата в админ панела продукти по подразбиране са с source admin.
• Идентичността на продукта е комбинацията от магазин, source и external ID. Batch и единичните POST upsert операции са пълни замени, не patch заявки: пропуснатите незадължителни полета се изчистват. Използвайте PATCH за частични обновявания.
• Партидите съдържат 1–50 продукта и най-много 2,000,000 байта в заявката. Валидираният JSON на всеки продукт е ограничен до 128,000 байта, с най-много 250 варианта.
• Предпочитайте десетични низове за цените. Валутата е трибуквен код с главни букви.
• URL адресите на продуктите и изображенията трябва да са HTTP(S). Импортирането не извлича тези URL адреси вместо вас.
• Използвайте публични metafields за продуктови спецификации, които могат да се търсят (аналогът на SiteChat на Shopify product metafields). Стойностите трябва да са обикновени низове. Старото attributes се приема като псевдоним. Частното продуктово metadata вече не се поддържа.
• Продукти със статус draft и archived се пропускат от следващия публикуван индекс. Публикуваните, но изчерпани продукти остават индексирани с приложена информация за наличност.
• Ръчните колекции съхраняват заглавие, описание, статус и списък с членства на продукти (source + external_id). Умни/базирани на правила колекции не се поддържат в тази версия.

Примерен успешен отговор

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

Shoply валидира цялата заявка преди запис. HTTP 200 все пак може да изброява някои резултати в failed с error: "storage_error". Проверявайте всеки резултат и опитайте отново неуспешните продукти. Ако index_status е request_failed, записването е било успешно, но индексирането не е било планирано — опитайте отново и вече записаните продукти.

Пример с Python

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

Как да проверя импортиран продукт?

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

Използвайте същата заглавка Authorization. Отговорът включва schema_version, updated_at, index_status и нормализирания product. Липсващите записи връщат HTTP 404.

След като фоновият indexer публикува преизграждане, статусът при обратно прочитане на отделния продукт става indexed, excluded (за продукти в draft или archived) или limit_exceeded. Използвайте GET /merchant/products/list за админ списък. Меко архивирайте с DELETE /merchant/products (или задайте status на archived / draft), за да не допускайте продукт в следващия публикуван индекс; в тази версия няма твърдо изтриване.

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

Как безопасно да обновявам варианти или metafields?

За PATCH, съдържащ variants, metafields или старото поле attributes, първо прочетете продукта с GET. Изградете редакцията от този отговор и включете неговата стойност updated_at от най-горно ниво като expected_updated_at в тялото на PATCH. Това важи и при изчистване на варианти или metafields.

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 означава, че версията е липсвала или че друго обновяване е променило продукта. Прочетете най-новата версия на продукта и отново слейте желаните от вас промени, преди да опитате пак. Не добавяйте нова версия към стар списък с варианти: това може да презапише по-нови стойности за наличност.

Съществуващите интеграции, които правят PATCH на тези полета без версия, трябва да бъдат обновени. PATCH заявки само със скаларни стойности, специализираните корекции на наличностите и пълните замени чрез POST или batch import не изискват това поле. Пълните замени все пак заменят целия продукт.

Мога ли да качвам продуктови изображения?

Да. Ако изображение вече е налично на постоянен публичен HTTPS URL адрес, поставете този URL в списъка images на продукта или в полето image на вариант. Публични S3 HTTPS URL адреси работят. Сурови пътища s3:// и краткотрайни подписани URL адреси не работят.

За да оставите Shoply да хоства файла, качете суровите байтове на изображението от вашия бекенд:

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

Изпратете суровите байтове на файла, а не JSON, base64 или multipart form data. Приемат се JPEG, PNG и WebP, до 10 MiB и 20 милиона пиксела. Анимирани изображения не се поддържат. Shoply конвертира изображението в WebP и премахва вградените метаданни.

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 връща url, content_type, size_bytes, width и height. Самостоятелното качване на изображение не го прикачва към продукт и не заявява индексиране. Включете върнатия URL в завършен продукт и го изпратете отново чрез /merchant/products/batch.

Ако същото изображение бъде качено отново за същия акаунт, URL адресът му се преизползва. Променено изображение получава нов URL адрес. В тази версия няма крайна точка за изтриване на изображения.

Кога продуктите се появяват в чата и търсенето?

След успешно batch записване Shoply заявява фоново преизграждане на индекса. Отговорите отчитат index_status: "pending", докато worker-ът не публикува новия индекс. Няма гаранция за фиксирано време за завършване.

• Публикуваните продукти влизат както в продуктовото търсене, така и в знанието, използвано от чата на SiteChat.
• Черновите и архивираните продукти се изключват при следващото преизграждане.
• Ако индексирането не е било планирано (index_status: "request_failed"), опитайте отново batch заявката за продуктите, които вече са били успешно записани.

Какви грешки да очаквам?

Тайните изтичат след 90 дни. Създайте заместител в Settings → Store owner API secret преди изтичането и оттеглете всяка тайна, която вече не ви е нужна. Същата тайна може също да извиква крайните точки за анализи, разговори и знание, документирани в Merchant API guide.

За помощ с интеграция, свържете се с Shoply AI.