Документация

Два способа подключить поиск: готовый виджет одной строкой кода или API, если вёрстку выдачи вы рисуете сами.

Виджет

Скрипт ставится один раз перед закрывающим тегом </body>. Идентификатор магазина берётся в личном кабинете, раздел «Подключение».

<script src="https://api.poisk.plus/w.js" data-shop="ВАШ_ID" defer></script>

Виджет сам находит поле поиска на странице, открывает выдачу, считает статистику и обновляется вместе с каталогом. Цвет, положение кнопки, подсказка и анимация настраиваются в кабинете, раздел «Внешний вид».

Своё поле поиска и своя кнопка

Если поиск у вас уже вписан в шапку, плавающую кнопку можно выключить и повесить виджет на существующее поле:

<script src="https://api.poisk.plus/w.js" data-shop="ВАШ_ID"
        data-target=".header__search input" data-button="off" defer></script>

data-target — CSS-селектор вашего поля поиска, клик по нему открывает виджет;
data-button="off" — не показывать плавающую кнопку;
data-position — угол кнопки: bottom-right или bottom-left, если нужно переопределить настройку из кабинета.

Вызов из кода

После загрузки скрипт публикует объект Poisk — им поиск открывается по любому вашему событию: своя кнопка в шапке, пункт меню, горячая клавиша.

// открыть поиск по своей кнопке
document.querySelector('.my-search').addEventListener('click', function () {
  Poisk.open()
})

// открыть сразу с запросом
Poisk.open('кран шаровой')

// закрыть и узнать о закрытии
Poisk.close()
Poisk.onClose = function () { /* вернуть фокус, снять оверлей */ }

Поисковый API

Нужен, когда выдачу вы рисуете сами: своя вёрстка карточек, свои кнопки, своя логика наличия. Мы отвечаем за релевантность и порядок, вы — за внешний вид.

Доступен с тарифа Бизнес и работает только с выгрузкой YML/XML. Товары возвращаются в том виде, в каком пришли в вашем фиде: подойдёт обычный YML для Яндекс.Маркета, отдельную выгрузку под нас делать не нужно.

Не хватает поля в карточке — добавьте его в тот же фид: YML допускает произвольные теги, и мы вернём их рядом с остальными.

Ключ

Выдаётся в кабинете, раздел «Каталог», и передаётся заголовком X-Api-Key. Ключ принадлежит магазину — идентификатор сайта в запросах не нужен. Повторная выдача заменяет прежний ключ, отзыв выключает интеграцию сразу.

Ключ живёт только на вашем сервере. Не встраивайте его в код страницы или в мобильное приложение: оттуда его забирает кто угодно и получает доступ к каталогу от вашего имени. Схема такая: браузер зовёт ваш бэкенд, бэкенд — нас. По той же причине ключ не принимается параметром в адресе — query-строка попадает в логи и в Referer.

Если поиск нужен на фронте, проксируйте запрос через свой сервер — заодно сможете подмешать свои данные вроде остатков и персональных цен до отдачи в браузер.

Поиск

curl -H "X-Api-Key: КЛЮЧ" \
  "https://api.poisk.plus/api/search?q=кран&per_page=20"

Ответ:

{
  "query": "кран",
  "found": 508,
  "page": 1,
  "per_page": 20,
  "has_more": true,
  "corrected_query": null,
  "offers": [
    {
      "id": "31006",
      "available": true,
      "name": "кран шаровой PPRC комбинированный нр 25*3/4",
      "price": "717.64",
      "picture": ["https://ваш-магазин.ru/upload/a.jpg"],
      "param": [{ "name": "Артикул", "value": "50108" }],
      "_id": "68ea93d4f8d4d3f8",
      "_url": "https://ваш-магазин.ru/catalog/krany/31006/"
    }
  ]
}

Поля id, name, price, picture, param — из вашего фида. Служебных полей два: _id — наш идентификатор товара, его нужно вернуть при клике, и _url — канонический адрес карточки.

повторяющийся тег всегда приходит массивом — если хотя бы у одного товара две picture, это массив у всех;
атрибуты оффера поднимаются в корень: id, available;
значения остаются строками, кроме available — форматирование цены остаётся за вами;
атрибуты вложенных тегов сохраняются рядом со значением: { "name": "Ду", "unit": "мм", "value": "25" }.

Клики

POST https://api.poisk.plus/api/click
X-Api-Key: КЛЮЧ

{
  "query": "кран",
  "product_id": "68ea93d4f8d4d3f8",
  "product_name": "кран шаровой PPRC комбинированный нр 25*3/4",
  "product_url": "https://ваш-магазин.ru/catalog/krany/31006/"
}

Отправляйте при переходе покупателя в карточку. На кликах держатся популярные запросы, конверсия в кабинете и ранжирование товаров: без них статистика покажет поиски без переходов.

Обязательно: запасной поиск

Оставьте свой поиск рабочим и переключайтесь на него, если наш ответ не пришёл: сеть моргнула, лимит исчерпан, идут работы на нашей стороне. Покупатель не должен видеть пустую страницу из-за стороннего сервиса.

async function search(query) {
  try {
    const res = await fetch(
      'https://api.poisk.plus/api/search?q=' + encodeURIComponent(query),
      { headers: { 'X-Api-Key': process.env.POISK_KEY }, signal: AbortSignal.timeout(800) },
    )
    if (!res.ok) throw new Error('poisk: ' + res.status)
    return (await res.json()).offers
  } catch (e) {
    logger.warn(e)          // заметить проблему раньше покупателей
    return ownSearch(query) // свой поиск остаётся запасным
  }
}

Практика простая: таймаут в пределах секунды, любая ошибка или код ответа не 200 — показываем результаты своего поиска. Ошибку стоит писать в лог, чтобы вы заметили проблему раньше покупателей.

Лимиты и ошибки

Лимит зависит от тарифа: 500 запросов в минуту на «Бизнесе» и 1000 на «Корпоративном» и «Индивидуальном». Счётчик у API свой, отдельно от виджета, поэтому интеграция не делит квоту с покупателями. При превышении приходит 429, лимит восстанавливается в течение минуты.

Лимит считается на магазин, а не на адрес: он общий для всех ваших серверов. Если потолка не хватает, напишите нам, поднимем.

404 — неизвестный магазин, неверный или отозванный ключ, истёкший тариф;
422 — тело запроса не разобралось;
429 — превышен лимит запросов.

Для поиска на ввод ставьте дебаунс от 250 мс, как в виджете: иначе каждое нажатие клавиши уходит запросом и искажает статистику.

Остались вопросы

Напишите нам — support@poisk.plus. Поможем с подключением и разберём нестандартный фид.