ReplAI Feed — формат фида каталога

Универсальный способ передать AI-агенту ReplAI товары, акции и информационные страницы вашего сайта. Один контракт для любого стека: PHP, Python, Node, 1С-выгрузка или скрипт по расписанию.

Два способа доставки

Вариант A — push: вы отправляете нам

В кабинете ReplAI: Агент → Интеграции → Фид каталога → Сгенерировать ссылку. Получите URL вида:
```
https://api.replai.kg/rest/v1/sync/feed/catalog?token=<секрет>
```
Шлите на него POST с JSON-телом (Content-Type: application/json). Секрет в ссылке — единственная авторизация: храните её как пароль. Скомпрометирована — перегенерируйте в кабинете, старая ссылка сразу погаснет.

Вариант B — pull: мы забираем сами

Подходит, если на хостинге нет cron. Отдавайте тот же JSON по постоянному URL, укажите его в кабинете («URL фида») и нажмите «Забрать сейчас» для проверки. Дальше ReplAI опрашивает адрес каждые 30 минут; ответ трактуется как полный снимок (snapshot: true), если в JSON явно не указано иное. Ошибка последнего забора видна в кабинете.

Требования к URL: http(s), без логина/пароля в адресе, доступен из интернета (не localhost и не внутренний IP), без редиректов — давайте конечный адрес. Ответ до 15 МБ. Если фид «секретный», добавьте свой токен в query — мы сохраним адрес как есть.

Режим обновления

Рекомендуемый режим — полный снимок ("snapshot": true) раз в N часов: присылаете весь актуальный каталог, всё пропавшее из снимка скрывается автоматически. Для мгновенных обновлений («цена поменялась») шлите частичные push без snapshot — они ничего не скрывают.

Формат тела

{
  "snapshot": true,
  "generator": { "name": "my-shop-exporter", "version": "1.0.0" },
  "products": [
    {
      "external_id": "42-red-M",
      "name": "Куртка зимняя North",
      "price": "4500.00",
      "old_price": "6000.00",
      "special_until": "2026-08-15T23:59:59+06:00",
      "quantity": 7,
      "color": "красный",
      "size": "M",
      "description": "Мембрана 10K, утеплитель 200г.",
      "category": "Куртки",
      "is_active": true
    }
  ],
  "promotions": [
    {
      "external_id": "summer-sale",
      "title": "Летняя распродажа",
      "description": "Скидка 20% на всю обувь при заказе от 5000 сом.",
      "starts_at": "2026-07-20T00:00:00+06:00",
      "ends_at": "2026-08-10T23:59:59+06:00"
    }
  ],
  "pages": [
    {
      "external_id": "delivery",
      "title": "Доставка и оплата",
      "content": "Доставка по Бишкеку — бесплатно от 3000 сом...",
      "url": "https://myshop.kg/delivery"
    }
  ]
}

Все три секции опциональны — можно слать только товары или только акции.

generator (необязательно) — кто прислал фид: name ≤60 и version ≤20 символов. Мы показываем это владельцу магазина в кабинете; для готового OpenCart-расширения так работает подсказка «доступно обновление».

products — до 5000 за запрос

Поле	Тип	Обяз.	Описание
`external_id`	string ≤200	✅	Стабильный уникальный id товара/вариации у вас (ключ обновления: тот же id — тот же товар)
`name`	string ≤500	✅	Название
`price`	число/строка ≥0	✅	Текущая цена продажи (по акции — уже сниженная)
`old_price`	число/строка	—	Цена «было», зачёркнутая. Должна быть выше `price`, иначе пара игнорируется
`special_until`	ISO-дата	—	До какого момента действует акция; без таймзоны считаем UTC
`quantity`	int ≥0	—	Остаток (0 = нет в наличии)
`color`, `size`	string	—	Вариация
`description`	string ≤8000	—	Описание для агента
`category`	string ≤255	—	Название категории; создаётся автоматически
`is_active`	bool	—	`false` — скрыть товар у агента

promotions — до 200 за запрос

Акции попадают в Базу знаний агента: он рассказывает условия словами («скидка 20% на обувь до 10 августа»). Точные акционные цены конкретных товаров передавайте через old_price / special_until товара.

Поле	Тип	Обяз.	Описание
`external_id`	string ≤200	—	Стабильный id акции (иначе ключ — от названия)
`title`	string ≤400	✅	Название акции
`description`	string ≤8000	—	Условия
`starts_at`, `ends_at`	ISO-дата	—	Период. Акция с истёкшим `ends_at` игнорируется

pages — до 500 за запрос

Информационные страницы сайта (доставка, оплата, гарантия, о магазине) — тоже в Базу знаний: агент отвечает на вопросы клиентов по их содержимому.

Поле	Тип	Обяз.	Описание
`external_id`	string ≤200	—	Стабильный id страницы (иначе ключ — от URL/названия)
`title`	string ≤400	✅	Заголовок
`content`	string ≤100000	✅	Текст страницы (без HTML-тегов)
`url`	string ≤1000	—	Адрес страницы — агент даст клиенту ссылку

Ответ

{
  "products_received": 120,
  "products_created": 3,
  "products_updated": 117,
  "products_deactivated": 2,
  "products_skipped": 0,
  "skipped_reasons": [],
  "knowledge_created": 1,
  "knowledge_updated": 0,
  "knowledge_unchanged": 4,
  "knowledge_deleted": 0,
  "knowledge_skipped": 0
}

skipped_reasons: duplicate_external_id — повторный id в одном запросе; old_price_not_above_price — пара акции отброшена (товар сохранён).

Неверный или отключённый токен → 404. Ошибка валидации тела → 400 с описанием поля.

Пример: cron-скрипт

curl -X POST "https://api.replai.kg/rest/v1/sync/feed/catalog?token=СЕКРЕТ" \
  -H "Content-Type: application/json" \
  -d @feed.json

Правила и советы

snapshot: true скрывает только товары, ранее пришедшие из фида; заведённые вручную или из других интеграций не трогаются. То же с Базой знаний — удаляются только фидовые записи.
Пустой products при snapshot: true скроет весь фидовый каталог — не шлите снимок, если каталог не собрался.
Один товар в разных цветах/размерах — отдельные записи с разными external_id (например 42-red-M, 42-red-L).
Батчи больше лимита разбивайте на несколько запросов без snapshot, а затем шлите финальный снимок — либо держите каталог ≤5000 позиций на запрос.