Список служебных методов
| Метод | Адрес | Кто вызывает | Начинает сессию |
|---|---|---|---|
| Поиск по каталогу | 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-mail | GET /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 | гость и вошедший | нет |
Сценарий: форма обратной связи
GET /api/service/webForm— формы модуля «Веб-формы» (ID, название, текст кнопки).GET /api/service/webForm/field?webFormID=1— вопросы формы;varnameкаждого поля (например,form_text_586) — имя поля в теле отправки.POST /api/service/webForm— отправка:webFormIDи поля формы в теле. Метод начинает сессию, ID приходит в заголовкеX-Session-Id.
{
"data": [
{
"id": 586,
"title": "Фамилия, имя, отчество",
"titleType": "text",
"sid": "FULL_NAME",
"cSort": 100,
"required": "Y",
"fieldType": "text",
"varname": "form_text_586"
}
]
} 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"}' {
"data": {
"message": "Результат #15 успешно создан",
"success": true
}
} Проверка полей — как в компоненте form.result.new: незаполненное обязательное поле, неверный формат даты или файла — статус 400, тексты ошибок через «; » в errors. Без webFormID — статус 200 и ошибка в errors. Файлы передаются как multipart/form-data. Создаётся результат формы и уходят почтовые события и письма.
Сценарий: подписка на рассылку
GET /api/service/subscribe/rubrics— активные рассылки для формы в подвале.POST /api/service/subscribeсemailи необязательнымrubric(массив, JSON-массив или строка через запятую; без него — на все рассылки). Подписка создаётся подтверждённой, письмо подтверждения не отправляется, подписчик привязывается к сессии. Метод начинает сессию.GET /api/service/subscribe?email=...— на какие рассылки подписан e-mail.DELETE /api/service/subscribeсemailи необязательнымrubric— отписка; безrubric— от всех.
Ответ списка рассылок (поля — штатные поля рассылки Битрикса, сокращено):
{
"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 (карточки по набору «Список»).
{
"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].
Что почитать после служебных методов
- Сессия и авторизация:
X-Session-Idпосле отправки формы и подписки - Состав ответа: набор «Список» для карточек поиска
- Быстрый старт