hints.page.hints

Scope: hints

Кто может вызывать: RestAccess::requireRead() + модуль включён (switchOn=Y). Подробнее: Права доступа

Возвращает данные для фронтенд-рендера подсказок: payload как у виджета на портале (подсказки, якорные подсказки, тема, флаги показа).

HTTP: GET

Побочные эффекты: none (чтение).

Обязателен параметр filter или url. Параметр url автоматически добавляет filter[url][$eq]=…. Без фильтра — VALIDATION_ERROR.

Параметр force игнорирует факт просмотра: в ответе флаг show будет 0, даже если страница уже в ShowTable (как «вернуть сценарий, включая просмотренные»). Его включают boolean true, число 1 и строки "1", "on", "true", "y", "yes" без учёта регистра. Любое другое значение считается выключенным, в том числе false, 0, "0", "false", "off", "n", "no" и пустая строка; ошибка не возвращается. Без force при существующей записи просмотра show=1 (виджет не запускает тур повторно).

В JSON boolean передаётся без кавычек ("force": true), а строковый вариант — с кавычками ("force": "on"). Для GET-запроса в query можно передать force=true.

Параметры метода

Параметр Тип Обяз. Описание
limit int нет Размер страницы (default 50, max 500)
offset int нет Смещение
fetchAll bool нет Вернуть все записи (лимит 5000)
filter object да* Mongo-фильтр (*или url)
url string да* URL страницы; эквивалент filter[url][$eq]
force bool|int|string нет Включающие значения: true, 1, "1", "on", "true", "y", "yes"; остальные значения выключают force

Поля filter (Mongo)

Поддерживаемые поля: id, name, url, count.

Alias: sectionId, pageId, groupId → id.

Операторы: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin.

Фильтрация по count выполняется до пагинации. total, offset и limit рассчитываются по отфильтрованному результату. В выборку попадают только активные страницы (ACTIVE=Y).

Возвращаемые данные

result.result — массив объектов рендера; верхнеуровневые Bitrix next, total.

Поле Тип Описание
id int ID страницы
name string Название
url string URL
hints array Подсказки для пошагового сценария
anchorHints array Якорные подсказки
show int 0 — показывать сценарий; 1 — уже просмотрен (при force всегда 0)
theme string Тема (light / dark)
count int Число подсказок
showErrors int Флаг ошибок рендера

Элементы массива hints содержат поля виджета: id, name, selector, description, shape, event, timeout, showSkip, showNext, nextButton, skipButton, radius, show_by_anchor, show_by_queue, anchor, link_for_next_btn.

Обработка ошибок

Справочник кодов: error-codes.md.

Код Описание
UNAUTHORIZED Пользователь не авторизован
MODULE_DISABLED Модуль выключен на сайте
ACCESS_DENIED Нет права чтения
VALIDATION_ERROR Не указаны filter и url
INVALID_LIMIT limit вне 1..500
INVALID_OFFSET offset < 0
INVALID_FILTER Некорректный filter
INVALID_FILTER_OPERATOR Неизвестный оператор фильтра
FETCH_ALL_LIMIT_EXCEEDED Превышен лимит fetchAll
INTERNAL_ERROR Внутренняя ошибка сервера

Пример запроса (GET)

curl -G "https://76592.dev.wehive.digital/rest/1/{webhook_code}/hints.page.hints.json" \
          -H "Accept: application/json" \
          --data-urlencode "url=/company/" \
          --data-urlencode "force=true"

Пример ответа

{
          "result": {
            "result": [
              {
                "id": 94,
                "name": "(1) Поиск сотрудника",
                "url": "/company/",
                "hints": [
                  {
                    "id": 1075,
                    "name": "Поиск сотрудника",
                    "selector": "SPAN#pagetitle",
                    "description": "павпвап",
                    "shape": "rect",
                    "event": "",
                    "timeout": 1000,
                    "showSkip": true,
                    "showNext": true,
                    "nextButton": {
                      "className": "hint_button_next",
                      "text": "Далее"
                    },
                    "skipButton": {
                      "className": "hint_button_skip",
                      "text": "Завершить ознакомление"
                    },
                    "radius": 10,
                    "show_by_anchor": false,
                    "show_by_queue": true,
                    "anchor": "",
                    "link_for_next_btn": null
                  }
                ],
                "anchorHints": [],
                "show": 0,
                "theme": "light",
                "count": 1,
                "showErrors": 1
              }
            ],
            "error": null
          },
          "total": 1,
          "time": {
            "start": 1788357574,
            "finish": 1788357574.845256,
            "duration": 0.8452560901641846,
            "processing": 0,
            "date_start": "2026-09-02T16:59:34+03:00",
            "date_finish": "2026-09-02T16:59:34+03:00"
          }
        }

Пример ответа (ошибка: нет filter/url)

{
          "result": {
            "result": null,
            "error": {
              "code": "VALIDATION_ERROR",
              "message": "Укажите filter или url.",
              "details": {
                "fields": ["filter", "url"]
              }
            }
          },
          "time": {
            "start": 1788357586,
            "finish": 1788357586.337648,
            "duration": 0.3376479148864746,
            "processing": 0,
            "date_start": "2026-09-02T16:59:46+03:00",
            "date_finish": "2026-09-02T16:59:46+03:00"
          }
        }

См. также

Предыдущая
hints.page.delete
Следующая
Обзор раздела