Как настроить API в 1С: HTTP-сервисы, OData и публикация на веб-сервере

API в 1С — это способ обмениваться данными между информационной базой и внешними системами: сайтом, мобильным приложением, CRM или складской программой. Платформа 1С:Предприятие предоставляет два основных механизма: стандартный REST-интерфейс OData, который работает почти без программирования, и произвольные HTTP-сервисы, где разработчик сам определяет логику обработки запросов.

Выбор механизма зависит от задачи. OData подходит, когда нужно дать внешней системе доступ к справочникам и документам в стандартном виде — чтение, создание, изменение записей. HTTP-сервисы нужны, когда требуется нестандартная логика: сложная фильтрация, агрегация данных, обработка файлов, интеграция с очередями сообщений.

Оба механизма требуют публикации базы на веб-сервере (Apache или IIS), поэтому настройка API всегда состоит из двух частей: подготовки конфигурации и настройки веб-доступа. Ниже разобран полный порядок действий с проверкой результата на каждом этапе.

Что выбрать: OData или HTTP-сервисы

Стандартный интерфейс OData — это автоматически генерируемый REST API, который платформа создаёт на основе структуры метаданных конфигурации. После включения он предоставляет доступ к справочникам, документам, регистрам сведений и накопления по URL вида /base/odata/standard.odata/Catalog_Номенклатура. Писать код не нужно — достаточно включить механизм и опубликовать базу.

HTTP-сервис — это объект конфигурации, где разработчик описывает шаблоны URL и обработчики методов GET, POST, PUT, DELETE на встроенном языке 1С. Это даёт полный контроль: можно вернуть данные в любом формате, выполнить проверки перед записью, объединить несколько операций в один запрос.

На практике часто комбинируют оба подхода: OData — для справочников, HTTP-сервис — для бизнес-операций вроде «оформить заказ с резервированием». Учтите, что OData открывает доступ сразу ко многим объектам, поэтому права пользователя нужно настраивать особенно аккуратно.

Подготовка базы: пользователь и права доступа

Никогда не используйте для API учётную запись администратора или полные права. Создайте отдельного пользователя, например «APIUser», и назначьте ему только те роли, которые нужны для конкретной интеграции. Если внешняя система должна только читать номенклатуру — дайте право чтения этого справочника и ничего больше.

Для OData дополнительно проверьте, что у пользователя включено право «Использование стандартного интерфейса OData» — оно назначается в ролях конфигурации или через профиль группы доступа, если используется БСП (библиотека стандартных подсистем). Без этого права запросы будут возвращать ошибку 403 даже при корректной аутентификации.

Пароль для API-пользователя задайте сложный и храните его в конфигурации внешней системы, а не в коде. Если интеграций несколько, создайте отдельного пользователя под каждую — так проще отозвать доступ и отследить в журнале регистрации, какая система выполнила операцию.

Включение и публикация OData

Откройте конфигуратор, перейдите в свойства корневого узла конфигурации (правый клик по названию конфигурации → «Свойства»). Найдите параметр «Публиковать стандартный интерфейс OData» и установите его в значение «Использовать». В типовых конфигурациях этот параметр иногда уже включён — проверьте перед изменением.

Далее опубликуйте базу на веб-сервере: меню «Администрирование» → «Публикация на веб-сервере». Укажите имя публикации (латиницей, без пробелов), каталог и в списке публикуемых сервисов отметьте «Стандартный интерфейс OData». После публикации платформа создаст файл default.vrd и настройки виртуального каталога.

Проверка выполняется прямо из браузера. Откройте адрес вида http://server/base/odata/standard.odata — должна появиться XML-страница со списком доступных сущностей после ввода логина и пароля API-пользователя. Если страница открылась, базовая настройка завершена.

1. 1
   Создайте отдельного пользователя с минимальными правами и правом использования OData
2. 2
   В свойствах конфигурации включите публикацию стандартного интерфейса OData
3. 3
   Опубликуйте базу на веб-сервере с отметкой сервиса OData
4. 4
   Проверьте в браузере URL /odata/standard.odata с авторизацией
5. 5
   Выполните тестовый запрос к конкретной сущности, например Catalog_Номенклатура

Создание HTTP-сервиса в конфигураторе

В дереве конфигурации найдите ветку «Общие» → «HTTP-сервисы» и добавьте новый объект. Задайте имя, например «IntegrationAPI», и в свойстве «Корневой URL» укажите префикс, например api. Тогда все запросы к сервису будут начинаться с /base/api/.

Внутри сервиса создайте шаблон URL, например /products/{id}, и для него — метод GET с обработчиком. В обработчике пишется код на встроенном языке: получение параметра, запрос к базе, формирование ответа. Пример минимального обработчика:

Функция ПолучитьНоменклатуру(Запрос)
Ид = Запрос.ПараметрыURL["id"];
Ответ = Новый HTTPСервисОтвет(200);
// ... запрос к базе, формирование JSON ...
Ответ.УстановитьТелоИзСтроки(СтрокаJSON);
Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
Возврат Ответ;
КонецФункции

После создания сервиса его нужно включить в публикацию: в диалоге публикации на веб-сервере на закладке «HTTP-сервисы» отметьте созданный объект. Без этого шага запросы будут возвращать ошибку 404 даже при корректном коде.

Настройка аутентификации и защита API

По умолчанию HTTP-сервисы и OData используют базовую аутентификацию 1С: логин и пароль передаются в заголовке Authorization. Это работает из коробки, но безопасно только по HTTPS. Настройте SSL-сертификат на веб-сервере и принудительно перенаправляйте HTTP на HTTPS.

Дополнительные меры, которые стоит применить: ограничение доступа по IP-адресам на уровне веб-сервера или файрвола, отдельный порт или поддомен для API, отключение публикации тонкого клиента и веб-клиента на том же виртуальном каталоге, если они не нужны. Каждый лишний опубликованный сервис — потенциальная точка входа.

Для HTTP-сервисов можно реализовать собственную проверку токена в начале каждого обработчика: внешняя система передаёт ключ в заголовке, а код 1С сверяет его со значением в константе или регистре сведений. Это позволяет отозвать доступ без смены пароля пользователя.

Тестирование и проверка результата

Тестировать API удобнее всего через curl, Postman или аналогичный инструмент — браузер подходит только для простых GET-запросов OData. Проверьте три сценария: успешный запрос с корректными данными, запрос с неверным паролем (должен вернуться 401), запрос к несуществующему ресурсу (404).

curl -u APIUser:password "https://server/base/odata/standard.odata/Catalog_Номенклатура?$top=5&$format=json"

Для HTTP-сервисов проверьте дополнительно: передачу параметров в URL и в теле запроса, обработку кириллицы в JSON (кодировка должна быть UTF-8), поведение при пустых и некорректных значениях. Ошибки в обработчике логируйте через запись в журнал регистрации — иначе при сбое вы увидите только «500 Internal Server Error» без деталей.

Типичные ошибки и ограничения

Самая частая проблема — ошибка 404 при корректном URL. Причина почти всегда одна: сервис не отмечен в настройках публикации или публикация выполнена в другой каталог, чем ожидает внешняя система. Проверьте файл default.vrd и фактический путь в конфигурации веб-сервера.

Вторая группа проблем — производительность. OData-запросы без фильтров выгружают таблицы целиком, а обработчики HTTP-сервисов, открывающие транзакции на запись, могут блокировать работу пользователей. Всегда используйте параметры $filter и $top в OData и не выполняйте тяжёлые операции синхронно в обработчике.

Помните и об ограничениях платформы: стандартный OData не поддерживает произвольные запросы и хранимые процедуры, а HTTP-сервисы выполняются в контексте сеанса 1С и расходуют лицензии или соединения в зависимости от режима лицензирования. При высокой нагрузке рассмотрите вынос интеграционной логики в отдельную базу-шину или брокер сообщений.

Частые вопросы