Сервисы и производительность тема 21 из 27

Служебные методы: поиск, формы, подписка, карты

Группа /api/service собирает методы, которые нужны витрине вокруг каталога: поиск, веб-формы, рассылки, конфигурация фронтенда, адреса и подсказки, защита форм. Все методы открыты гостю. Сессию начинают только отправка веб-формы и подписка на рассылку.

в этой теме 8
  1. Список служебных методов
  2. Сценарий: форма обратной связи
  3. Сценарий: подписка на рассылку
  4. Поиск, конфигурация фронтенда
  5. Карты, подсказки адреса, защита форм
  6. Где настраиваются служебные методы
  7. Ограничения служебных методов
  8. Что почитать после служебных методов

Список служебных методов

МетодАдресКто вызываетНачинает сессию
Поиск по каталогуGET /api/service/searchгость и вошедшийнет
Конфигурация фронтендаGET /api/service/configгость и вошедшийнет
Список веб-формGET /api/service/webFormгость и вошедшийнет
Поля веб-формыGET /api/service/webForm/fieldгость и вошедшийнет
Отправить ответы веб-формыPOST /api/service/webFormгость и вошедшийда
Рассылки для подпискиGET /api/service/subscribe/rubricsгость и вошедшийнет
Рассылки e-mailGET /api/service/subscribeгость и вошедшийнет
ПодписатьсяPOST /api/service/subscribeгость и вошедшийда
ОтписатьсяDELETE /api/service/subscribeгость и вошедшийнет
Яндекс.Карты: адрес по координатамGET /api/service/geocodeгость и вошедшийнет
Яндекс.Карты: координаты по адресуGET /api/service/geocode/reverseгость и вошедшийнет
DaData: организация по ИНН или ОГРНGET /api/service/organization/searchгость и вошедшийнет
DaData: подсказки адресаGET /api/service/suggest/addressгость и вошедшийнет
DaData: адрес по координатамGET /api/service/geolocate/addressгость и вошедшийнет
reCAPTCHA: ключ сайтаGET /api/service/googleCaptchaгость и вошедшийнет
reCAPTCHA: проверка ответаPOST /api/service/googleCaptchaгость и вошедшийнет

Сценарий: форма обратной связи

  1. GET /api/service/webForm — формы модуля «Веб-формы» (ID, название, текст кнопки).
  2. GET /api/service/webForm/field?webFormID=1 — вопросы формы; varname каждого поля (например, form_text_586) — имя поля в теле отправки.
  3. POST /api/service/webForm — отправка: webFormID и поля формы в теле. Метод начинает сессию, ID приходит в заголовке X-Session-Id.
json
{
    "data": [
        {
            "id": 586,
            "title": "Фамилия, имя, отчество",
            "titleType": "text",
            "sid": "FULL_NAME",
            "cSort": 100,
            "required": "Y",
            "fieldType": "text",
            "varname": "form_text_586"
        }
    ]
}
bash
curl -i -X POST "https://example.ru/api/service/webForm" \
  -H "Content-Type: application/json" \
  -d '{"webFormID": 1, "form_text_586": "Иванов Иван", "form_date_587": "01.06.1904"}'
json
{
    "data": {
        "message": "Результат #15 успешно создан",
        "success": true
    }
}

Проверка полей — как в компоненте form.result.new: незаполненное обязательное поле, неверный формат даты или файла — статус 400, тексты ошибок через «; » в errors. Без webFormID — статус 200 и ошибка в errors. Файлы передаются как multipart/form-data. Создаётся результат формы и уходят почтовые события и письма.

Сценарий: подписка на рассылку

  1. GET /api/service/subscribe/rubrics — активные рассылки для формы в подвале.
  2. POST /api/service/subscribe с email и необязательным rubric (массив, JSON-массив или строка через запятую; без него — на все рассылки). Подписка создаётся подтверждённой, письмо подтверждения не отправляется, подписчик привязывается к сессии. Метод начинает сессию.
  3. GET /api/service/subscribe?email=... — на какие рассылки подписан e-mail.
  4. DELETE /api/service/subscribe с email и необязательным rubric — отписка; без rubric — от всех.

Ответ списка рассылок (поля — штатные поля рассылки Битрикса, сокращено):

json
{
    "data": {
        "success": true,
        "rubrics": [
            { "id": "1", "name": "Новости магазина", "active": "Y", "description": "Ежедневная рассылка новостей магазина." }
        ]
    }
}

Если модуль «Подписка» не установлен, тело ответа пустое. Ошибка Битрикса при подписке — статус 200, текст в error.

Поиск, конфигурация фронтенда

GET /api/service/search — строка поиска витрины. Параметры: searchable_content (что искать, обязателен: без него 400) и iblock_codes (коды инфоблоков через запятую, необязателен). Искать можно только по инфоблокам из настройки «Инфоблоки, по которым выполняется поиск»; если она пуста — только по открытым для REST; прочие коды молча отбрасываются. Ответ сгруппирован по API-коду инфоблока: sections (разделы с числом элементов, пустые не показываются) и elements (карточки по набору «Список»).

json
{
    "catalog": {
        "sections": [ { "id": 3, "name": "Футболки", "elementsCount": 12 } ],
        "elements": [ { "id": 105, "name": "Футболка базовая" } ]
    }
}

GET /api/service/config возвращает JSON из настройки «JSON-конфигурация фронтенда» как есть, без обёртки data: витрина получает адреса, флаги и тексты без пересборки.

Карты, подсказки адреса, защита форм

  • geocode (lat, lon) и geocode/reverse (location) работают через HTTP Геокодер Яндекса. Ключ — «Ключи и токены» -> «Карты и адреса».
  • organization/search (inn, необязательный kpp) — автозаполнение реквизитов юридического лица на оформлении заказа через DaData. suggest/address (query, count) и geolocate/address (lat, lon) — подсказки адреса. Ключ DaData — «Ключи и токены» -> «Карты и адреса». Подсказки адреса доступны только со страниц витрины и сайтов из настройки CORS (без Origin и Referer — 403): платный ключ защищён.
  • GET /api/service/googleCaptcha отдаёт публичный ключ для виджета reCAPTCHA v2: {"data": {"siteKey": "..."}}. После прохождения виджета витрина отправляет его токен в POST /api/service/googleCaptcha (response); успех — {"data": {"success": true}}, иначе 400. Ключи — «Ключи и токены» -> «Защита форм».

Если ключ сервиса не задан, методы отвечают статусом 200 и errors[0].code = ERR_SERVICE_NOT_CONFIGURED.

Где настраиваются служебные методы

ЧтоГде
Инфоблоки поиска, лимиты разделов и записей поискаНастройки модуля -> «Основное», блок «Поиск»
JSON-конфигурация фронтенда«Основное», блок «Фронтенд»
Сайты, которым разрешены подсказки адреса«Основное», «Сайты, с которых разрешены запросы к API из браузера» (Сессия и авторизация)
Ключи Яндекс.Карт, DaData, reCAPTCHAвкладка «Ключи и токены»
Рассылки, веб-формыштатные разделы Битрикса (модули «Подписка» и «Веб-формы»)

Ограничения служебных методов

  • POST /api/service/subscribe: гость без параметра email подписывается на пустой адрес (берётся e-mail текущего пользователя, у гостя он пуст). Гостю всегда передавайте email.
  • Часть ошибок приходит телом {errors: [...]}, часть — {success: false, error: текст}: читайте текст из error или errors[0].

Что почитать после служебных методов

Подключим BIK.REST-API к вашему сайту

Оставьте заявку — установим и настроим модуль, ответим на вопросы по API.

c заботой о вас, мы используем cookie на своем сайте, чтобы интернет был чистым и прекрасным