Как да качите каталога си за 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: Как да използвате 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 скрипт, 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.

След като фоновият индексатор публикува преизграждане, статусът при обратно прочитане за отделен продукт става 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"])

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

Да. Ако изображение вече е налично на постоянен публичен 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. В тази версия няма крайна точка за изтриване на изображения.

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

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

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

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

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

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