REST API в 1С: что это и как с ним работать

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

В 1С есть два основных пути реализации REST-подхода. Первый — встроенный интерфейс OData, который платформа публикует автоматически и который позволяет читать и изменять данные без написания кода. Второй — собственные HTTP-сервисы, которые разработчик создаёт в конфигураторе и в которых описывает произвольную логику обработки запросов. Оба варианта работают через веб-сервер (IIS или Apache) и требуют публикации базы.

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

Что такое REST API простыми словами

REST (Representational State Transfer) — это архитектурный стиль обмена данными, при котором системы общаются через стандартные HTTP-методы: GET для чтения, POST для создания, PUT и PATCH для изменения, DELETE для удаления. Каждый объект данных (документ, элемент справочника) адресуется по URL, а ответ обычно возвращается в формате JSON или XML.

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

Два способа реализовать REST API в 1С

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

Второй способ — собственные HTTP-сервисы. В конфигураторе создаётся объект «HTTP-сервис», в нём описываются шаблоны URL (например, /api/orders/{id}) и методы-обработчики. Внутри обработчика доступен весь функционал встроенного языка: запросы к базе, проверки, проведение документов, формирование ответа произвольной структуры.

Как включить и опубликовать OData

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

После настройки базу нужно опубликовать на веб-сервере (Apache или IIS) с включённым флажком публикации интерфейса OData. Проверка выполняется запросом из браузера или Postman к адресу сервисного документа: если в ответ приходит XML со списком наборов сущностей, публикация работает. Дальше внешняя система может выполнять GET-запросы с фильтрами ($filter, $select) и POST-запросы для создания объектов.

1. 1
   Откройте конфигуратор и включите публикацию стандартного интерфейса OData в свойствах конфигурации
2. 2
   Отметьте в дереве метаданных только те объекты, которые нужны внешней системе
3. 3
   Опубликуйте базу на веб-сервере с включённой опцией OData
4. 4
   Создайте отдельного пользователя с минимально необходимыми правами для интеграции
5. 5
   Проверьте сервисный документ GET-запросом и выполните тестовое чтение одного справочника

Как создать собственный HTTP-сервис

HTTP-сервис добавляется в конфигураторе в ветке «Общие — HTTP-сервисы». Для сервиса задаётся корневой URL (например, api), внутри создаются шаблоны URL с параметрами в фигурных скобках и методы (GET, POST и другие), каждому из которых назначается обработчик — функция на встроенном языке.

В обработчике типовой сценарий выглядит так: прочитать параметры запроса и тело, проверить обязательные поля, выполнить операции с базой, сформировать структуру ответа, сериализовать её в JSON через ЗаписьJSON и вернуть с правильным HTTP-кодом. Ошибки важно обрабатывать явно: при некорректных данных возвращайте код 400 с описанием проблемы, при отсутствии объекта — 404, при внутренней ошибке — 500, а не «успешный» ответ с пустым телом.

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

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

Аутентификация и безопасность

Опубликованная база доступна из сети, поэтому безопасность — не опция, а обязательное условие. Минимальный набор: доступ только по HTTPS, отдельный пользователь 1С для интеграции с правами строго на нужные объекты, отсутствие у этого пользователя административных прав и права интерактивного входа, если он не нужен.

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

Проверка работы и типичные ошибки

Работоспособность API проверяется по трём признакам: запрос возвращает ожидаемый HTTP-код, тело ответа соответствует согласованному формату, данные в базе реально изменились (или не изменились при ошибке). Для тестирования удобно использовать Postman или аналог: сохраните набор запросов на чтение, создание и ошибочный сценарий и прогоняйте их после каждого изменения конфигурации.

Из практики чаще всего встречаются проблемы не в коде, а в окружении: не опубликован сервис на веб-сервере, не хватает прав у пользователя, неверный Content-Type в запросе, кодировка тела не UTF-8, из-за чего русские символы «ломаются». Диагностику начинайте с журнала регистрации 1С и логов веб-сервера — там видно, дошёл ли запрос до базы и на каком этапе произошёл отказ.

Когда REST API не подходит и что выбрать вместо

REST хорош для запросно-ответного обмена, но не для всех задач. Если нужна потоковая синхронизация больших объёмов между двумя базами 1С, надёжнее использовать планы обмена или EnterpriseData. Если внешняя система должна реагировать на события в 1С мгновенно и в большом количестве, рассмотрите брокеры сообщений, а не опрос API по расписанию.

Для простого одностороннего обмена с сайтом иногда достаточно штатных модулей обмена (например, обмена с сайтом в формате CommerceML), которые не требуют разработки вообще. Прежде чем писать собственный API, проверьте, не закрывает ли задачу типовой механизм конфигурации.

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