Документация и API
Всё для интеграции: REST API поиска, подсказок, рекомендаций, AI-консультанта и аналитики.
Подключение занимает от нескольких часов. Авторизация во всех методах — заголовок X-API-Key с токеном из личного кабинета (страница «Профиль»). Все ответы — JSON в UTF-8.
Первый запрос — проверьте, что каталог ищется:
curl -H "X-API-Key: ВАШ_ТОКЕН" \ "https://joyadmin.ru/api/search/?q=пакет+майка&limit=20"
{"status": "success", "total": 20, "time": 0.4,
"results": [{"id": "210013", "name": "...", "price": 8250,
"in_stock": true, "url": "...", "image": "...", "score": 12.3}]}Гибридный поиск (текстовый + векторный), исправление опечаток и раскладки, синонимы, буст товаров в наличии.
Основной поиск. Параметры: q — запрос, limit — до 500 результатов.
&page=2 — постраничный поиск (с 1, по умолчанию 1). Соседние страницы не пересекаются между собой. В ответе — page, total_matches (сколько всего найдено) и has_more (есть ли следующая страница), чтобы не считать это на своей стороне.
curl -H "X-API-Key: ВАШ_ТОКЕН" \ "https://joyadmin.ru/api/search/?q=пакет&limit=20&page=2"
{"status": "success", "page": 2,
"total_matches": 87, "has_more": true, "results": [...]}&fields=id — быстрый режим: в ответе только id и score, без названия, описания и цены. При больших limit ответ заметно легче и быстрее — пригодится, если карточки товара вам не нужны, а нужны только id (например, для своей синхронизации или пагинации).
curl -H "X-API-Key: ВАШ_ТОКЕН" \ "https://joyadmin.ru/api/search/?q=пакет&limit=500&fields=id"
{"status": "success", "total": 500,
"results": [{"id": "210013", "score": 12.3}, ...]}Сужайте выдачу по каталогу: category и vendor — точные значения (через запятую — несколько вариантов, логика ИЛИ), price_min/price_max — диапазон цены, in_stock=1 — только товары в наличии. Значения для category/vendor лучше брать из facets (см. ниже), а не вводить вручную — category_path часто хранится полным путём («Категория > Подкатегория»).
curl -H "X-API-Key: ВАШ_ТОКЕН" \ "https://joyadmin.ru/api/search/?q=пакет&category=Пакеты+Zip-lock&price_max=500"
&facets=1 — вернуть варианты фильтров с количеством подходящих товаров по текущему q. Список не сужается по мере выбора фильтров — всегда полный набор опций для запроса, удобно строить блок фильтров на странице выдачи.
{"status": "success", ...,
"facets": {"category": [{"value": "Пакеты Zip-lock", "count": 34}, ...],
"vendor": [{"value": "Мактуба", "count": 9}, ...],
"in_stock": {"true": 41, "false": 5},
"price": {"min": 45.0, "max": 3200.0}}}Мгновенные подсказки для выпадашки под поисковой строкой: популярные запросы вашего магазина (type=query, с частотой) и названия товаров (type=product, со ссылкой). Минимум 2 символа.
{"query": "пак", "suggestions": [
{"text": "пакет майка", "type": "query", "count": 11},
{"text": "Пакет ПВД 30*40", "type": "product", "url": "..."}]}Поиск по фото: изображение (multipart, поле image, до 8 МБ) распознаётся ИИ в текстовый запрос, дальше обычный поиск. В ответе — recognized_query и results.
curl -H "X-API-Key: ВАШ_ТОКЕН" \ -F "image=@photo.jpg" -F "limit=10" \ https://joyadmin.ru/api/search/image/
Рекомендации на векторах каталога и AI-консультант, который отвечает строго по данным товара.
Похожие товары для блока в карточке: ближайшие аналоги по смыслу (векторная близость), товары в наличии выше. product_id — тот же id, что возвращает поиск.
{"status": "success", "product_name": "Рукав ПВД 40 см, 50 мкм",
"results": [{"id": "210076", "name": "Рукав ПВД 40 см, 80 мкм", ...}]}AI-консультант в карточке товара. Параметры: product_id и question (form-data или JSON). Отвечает только на основе данных товара — характеристики, цена, наличие; не выдумывает.
curl -X POST -H "X-API-Key: ВАШ_ТОКЕН" \
-d "product_id=210013" \
-d "question=Какая толщина и есть ли в наличии?" \
https://joyadmin.ru/api/assistant/ask/
→ {"status": "success", "answer": "Толщина рукава — 50 мкм, товар в наличии."}События превращают статистику в деньги: CTR, конверсия и выручка поиска. Плюс методы для синхронизации каталога и выгрузки аналитики.
Маячок событий: type = click | add_to_cart | purchase, q — поисковый запрос, product_id, pos — позиция в выдаче, revenue — сумма для покупки. Всегда отвечает 204 и не задерживает страницу.
fetch('https://joyadmin.ru/api/search/event/'
+ '?type=add_to_cart'
+ '&q=' + encodeURIComponent(query)
+ '&product_id=210013&revenue=8250',
{ headers: { 'X-API-Key': 'ВАШ_ТОКЕН' }, keepalive: true });Вся аналитика кабинета в JSON: тоталы с динамикой, CTR, скорость поиска, устройства, таймлайн, топы запросов и товаров. Дубли склеены, боты отфильтрованы.
Точечное обновление цен и остатков — сразу в базе и в поисковом индексе, без перезагрузки прайса. До 500 товаров за запрос.
curl -X POST -H "X-API-Key: ВАШ_ТОКЕН" -H "Content-Type: application/json" \
-d '{"products": [{"id": "210013", "price": 8250, "in_stock": true}]}' \
https://joyadmin.ru/api/products/update/Загрузка прайса по расписанию: multipart-поле file (YML/XML/CSV) или параметр url. Ответ 202 с upload_id, обработка в фоне — статус по GET /api/upload/status/?id=...
Ранжирование и выдача настраиваются без разработчика — в личном кабинете JoyAdmin, раздел «Настройки поиска» (в меню слева). Изменения применяются сразу и сразу видны в ответах /api/search/ — переподключать сайт не нужно.
Насколько совпадение запроса с полем товара весит при ранжировании: Название (0.5–50, по умолчанию 10), Бренд (0–50, по умолчанию 3), Категория (0–50, по умолчанию 3), Описание (0–50, по умолчанию 2). Например, если покупатели ищут по артикулу или модели, которая чаще встречается в описании, стоит поднять вес описания.
Три режима: «не влияет на порядок», «товары в наличии выше» (с настраиваемым приоритетом 1–10, по умолчанию 1.3) и «скрывать отсутствующие» — этот последний режим убирает товары не в наличии из выдачи /api/search/ полностью, независимо от параметра in_stock в запросе.
Исправление опечаток: выключено / умеренно (рекомендуется) / агрессивно (до 2 ошибок в слове). Отдельно — переключатели «исправлять раскладку клавиатуры» и «использовать синонимы». Плюс список стоп-слов (через запятую или с новой строки) — игнорируются при поиске, полезно для слов вроде «купить», «цена», «недорого», которые не помогают найти товар.
Если включено — товары, которые чаще кликают и покупают именно по этому запросу, поднимаются выше (приоритет кликов и покупок настраивается отдельно, 1–20, по умолчанию 3 и 6). Данные берутся из маячков /api/search/event/ — без них накапливать нечего.
Отбрасывает результаты слабее N% от лучшего по релевантности (0–50%). 0 — показывать всё, включая слабо релевантное; 30–40% — только близкое к запросу. Влияет и на total_matches в ответе поиска.
Результатов по умолчанию (1–500, по умолчанию 40) — используется, если запрос к /api/search/ пришёл без параметра limit. Похожих товаров в блоке (1–20, по умолчанию 8) — дефолт для /api/recommend/similar/. «Разрешить сортировку по цене» включает/выключает параметр sort=price_asc/price_desc в публичном API. Отдельно — «скрытые категории» (по одной на строку) — категории, полностью исключённые из поиска.
Закреплённые товары — товар всегда первый по конкретному запросу (для акций и приоритетных позиций), задаётся парой «запрос → артикул». Скрытые товары — конкретный товар не показывается в поиске, но остаётся в каталоге и доступен по прямой ссылке. Приоритет категорий — вся категория целиком поднимается выше остальных (множитель ×0.1–×10); понизить категорию так нельзя — для этого используйте «скрытые категории» или поднимите приоритет у конкурирующей категории.