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

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

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

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

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

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

Например, запрос GET по адресу вида /odata/standard.odata/Catalog_Номенклатура вернёт список номенклатуры, а POST на адрес документов создаст новый документ в базе. Ответ приходит в структурированном виде, который легко разобрать программно.

Важно понимать: REST API не является отдельным продуктом 1С. Это механизм платформы «1С:Предприятие», который нужно включить, опубликовать и защитить. Без публикации базы на веб-сервере никакие внешние запросы к ней не попадут.

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

Платформа предлагает два принципиально разных подхода, и выбор между ними определяет объём работ, гибкость и требования к безопасности.

Стандартный интерфейс OData

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

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

Собственные HTTP-сервисы

HTTP-сервис — это объект конфигурации, который разработчик создаёт в конфигураторе. Для него задаются шаблоны URL (например, /hs/orders/{id}) и пишутся обработчики методов GET, POST и других на встроенном языке 1С. Внутри обработчика можно выполнить любую логику: проверить данные, создать несколько связанных объектов, вернуть произвольную структуру ответа.

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

Как включить и опубликовать стандартный интерфейс OData

Публикация выполняется на веб-сервере — IIS (Windows) или Apache (Linux/Windows). Файловая база без веб-сервера по REST недоступна в принципе: нужен либо клиент-серверный вариант, либо файловая база, опубликованная через веб-сервер.

1. 1
   Установите и настройте веб-сервер (IIS или Apache) и модули расширения веб-сервера 1С.
2. 2
   В конфигураторе откройте «Администрирование → Публикация на веб-сервере», укажите имя публикации и каталог.
3. 3
   На вкладке публикации включите флажок «Публиковать стандартный интерфейс OData» (для HTTP-сервисов — соответствующий флажок).
4. 4
   Выполните публикацию и перезапустите веб-сервер.
5. 5
   Проверьте доступность: откройте в браузере адрес вида http://сервер/ИмяПубликации/odata/standard.odata и убедитесь, что возвращается список объектов.

После публикации базовый адрес интерфейса выглядит так: http://сервер/ИмяБазы/odata/standard.odata/. Запрос к этому корню возвращает перечень доступных объектов метаданных. Далее к адресу добавляется имя объекта: Catalog_Контрагенты, Document_РеализацияТоваровУслуг и так далее.

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

GET http://server/base/odata/standard.odata/Catalog_Номенклатура?$format=json&$top=10 HTTP/1.1
Authorization: Basic <base64(пользователь:пароль)>

Как выполнять запросы: фильтры, выбор полей, создание объектов

OData поддерживает параметры запроса в URL. Основные: $filter — отбор записей, $select — список полей, $top и $skip — постраничная выборка, $orderby — сортировка. Пример: получить 20 контрагентов с отбором по наименованию и вывести только нужные поля.

GET .../odata/standard.odata/Catalog_Контрагенты?$format=json&$filter=contains(Description,'Альфа')&$select=Ref_Key,Description,ИНН&$top=20

Создание объекта выполняется методом POST с телом в формате JSON. В теле передают значения реквизитов; ссылочные поля заполняют через ключи вида Контрагент_Key с GUID элемента. Изменение — методом PATCH по адресу конкретного объекта (с GUID в URL), удаление — методом DELETE.

Для собственных HTTP-сервисов формат запросов полностью определяет разработчик. Типовая практика — принимать и возвращать JSON, при ошибках отдавать осмысленные HTTP-коды (400 для некорректного запроса, 401 для неавторизованного, 500 для внутренней ошибки) и текст причины в теле ответа.

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

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

Обязательное правило — создать для интеграции отдельного пользователя с минимально необходимыми правами. Не используйте учётную запись администратора: при утечке логина злоумышленник получит полный доступ к базе, включая удаление данных.

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

Ограничения, производительность и типичные ошибки

Каждый REST-запрос — это сеанс с базой: соединение, аутентификация, выполнение кода. Массовые обращения (например, выгрузка тысяч товаров по одному запросу на объект) создают заметную нагрузку. Правильный подход — забирать данные пачками через $top/$skip или списками в одном запросе, а не циклом по одному элементу.

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

Как проверить, что интеграция работает правильно

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

Для отладки удобны инструменты вроде Postman или curl: они показывают точный текст запроса и ответа, включая заголовки и коды состояния. Журнал регистрации 1С помогает увидеть ошибки на стороне сервера, а логи веб-сервера — проблемы публикации.

Часто задаваемые вопросы