Синхронизация каталога (API)

Если ваши товары, цены и остатки живут в учётной системе - 1С, CRM, складской программе или Google-таблице - их не нужно вносить в базу знаний вручную. Платформа принимает каталог по API: ваша система присылает данные, а ИИ-сотрудник сразу отвечает клиентам по актуальным позициям - «есть в наличии», «осталось 2 шт.», «цена 95 000 сом», «доступна рассрочка».

Когда это нужно

• Каталог большой и/или часто меняется (цены, остатки).
• Данные уже есть в 1С или другой системе - и вы хотите, чтобы они обновлялись автоматически.
• Нужно, чтобы ИИ не путался: товар закончился - бот честно скажет «нет в наличии».

Что относится к каталогу, а что - к Бизнес-профилю

Каталог (этот API) - это факты по каждой позиции: что за товар, где, сколько, в наличии или нет, можно ли в рассрочку/кредит.

Условия и правила - в Бизнес-профиле: как работает доставка, на каких условиях рассрочка и кредит (банки, сроки), адреса и часы работы точек, возвраты, гарантия.

Правило: каталог отвечает на «есть / нет / сколько / где / почём + флаги», профиль - на «как это работает». Адрес точки не дублируется в каждом товаре: товар несёт код точки (store_code), а адрес подставляется из профиля.

Шаг 1. Получите API-ключ

В кабинете → Настройки → API-токены создайте ключ. Он показывается один раз - сохраните его. Ключ вида atla_... привязан к вашей организации: данные пишутся только в ваш каталог, чужие недоступны.

Ключ передаётся в каждом запросе в заголовке:

Authorization: Bearer atla_ваш_ключ

Шаг 2. Отправьте товары

POST https://ai.atlabyte.com/api/v1/sync/items

Тело запроса (JSON):

{
  "source": "1c",
  "mode": "upsert",
  "items": [
    {
      "external_id": "store7:P1",
      "title": "iPhone 15 128GB",
      "category": "Смартфоны",
      "price": 95000,
      "currency": "KGS",
      "available": true,
      "stock": 3,
      "store_code": "ГУМ",
      "installment": true,
      "credit": true,
      "attributes": { "цвет": "чёрный", "память": "128GB" },
      "url": "https://shop.example/p1",
      "image_url": "https://shop.example/p1.jpg"
    }
  ]
}

Пример на curl:

curl -X POST https://ai.atlabyte.com/api/v1/sync/items \
  -H "Authorization: Bearer atla_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d @catalog.json

Поля товара

Поле	Обяз.	Описание
external_id	да	Стабильный идентификатор товара в вашей системе. По нему идёт обновление - не меняйте его для одной и той же позиции.
title	да	Название товара (на вашем языке - оно и попадёт к клиенту).
category	-	Категория («Смартфоны», «Стиральные машины»).
price	-	Цена (число).
currency	-	Валюта, напр. KGS, USD.
available	-	Наличие, true/false. Если не прислать - вычислим из stock.
stock	-	Остаток (число). Хранится и виден вам всегда. Клиенту точное число агент называет только если включена галка «Озвучивать клиенту точное количество остатка» (в разделе Базы знаний; по умолчанию выкл - агент говорит лишь «в наличии / нет»).
store_code	-	Код точки/склада. Адрес подставится из Бизнес-профиля.
installment	-	Доступна ли рассрочка на товар (true/false). Условия - в профиле.
credit	-	Доступен ли кредит на товар (true/false). Условия - в профиле.
attributes	-	Любые характеристики «ключ-значение»: { "цвет": "чёрный", "память": "128GB" }. Подходит для любой сферы.
url, image_url	-	Ссылка на товар и картинку.

source - метка системы-источника ("1c", "crm", "sheets"…). Это просто тег для группировки: API не привязан к 1С, подойдёт любая система, присылающая JSON в этом формате.

Режимы (mode)

• upsert (по умолчанию) - добавить новые и обновить существующие позиции по external_id. Ничего не удаляется только потому, что товара не было в этой посылке - случайной потери данных не будет.
• delete - удалить перечисленные позиции (нужны только их external_id).

Товар закончился? Лучший путь - прислать его же с available: false (позиция останется, бот скажет «нет в наличии» и предложит альтернативу). delete - для окончательного снятия с продажи.

Отправка напрямую из 1С (русские поля)

Если выгрузка идёт прямо из 1С, не нужно переводить поля в английскую схему — есть отдельный приём в нативном формате 1С:

POST https://ai.atlabyte.com/api/v1/sync/1c

Тело — стандартный дамп 1С {Точки, Товары, Остатки}:

{
  "Точки": [
    { "Код": 7, "Наименование": "МТ ЦЕНТР" }
  ],
  "Товары": [
    {
      "Код": "P1",
      "Наименование": "iPhone 15 128GB",
      "Цена": 95000,
      "ГруппаТоваров": "Смартфоны",
      "Рассрочка": true,
      "Кредит": true
    }
  ],
  "Остатки": [
    { "КодТочки": 7, "КодТовара": "P1", "Остаток": 3 }
  ]
}

• Идентификатор товара формируется как КодТочки:КодТовара — товар в разных точках учитывается отдельно.
• Остаток → наличие (> 0 = в наличии) и количество.
• Наименование точки используется как код точки; адрес подставляется из Бизнес-профиля.
• Рассрочка / Кредит — флаги доступности на товар (условия — в профиле).
• Авторизация и режим те же: заголовок Authorization: Bearer atla_…, обновление по external_id, без удаления отсутствующих (закончившийся товар шлите с Остаток: 0).

Внутри платформы оба формата сводятся к одной схеме и одному обработчику — английский для интеграторов, русский 1С-приём для удобства выгрузки.

Шаг 3. Проверьте, что попало в каталог

GET https://ai.atlabyte.com/api/v1/items

Возвращает ваши позиции с фильтрами и постраничной выдачей - удобно убедиться, что синхронизация прошла, или свериться по точке/модели.

curl "https://ai.atlabyte.com/api/v1/items?store_code=ГУМ&available=true&q=iPhone&limit=50" \
  -H "Authorization: Bearer atla_ваш_ключ"

Доступные фильтры: source, store_code, category, available, installment, credit, q (поиск по названию), price_min, price_max, limit (до 200), cursor (для следующей страницы).

Как часто слать

Шлите по расписанию (например, раз в час или после изменений в 1С) либо при каждом обновлении остатков. Повторная отправка безопасна и дешёвая: платформа сама определяет, что реально изменилось, и переобучает только изменившиеся позиции - можно слать весь каталог хоть каждый час без лишней нагрузки. За один запрос - до 5000 позиций; большой каталог разбейте на пачки.

Что увидит клиент

После синхронизации ИИ-сотрудник отвечает строго по вашим данным: подтверждает наличие, называет цену, говорит про рассрочку/кредит, ориентирует по точкам. Нет позиции в каталоге - не выдумывает, а честно сообщает и предлагает альтернативу или передаёт оператору.