1С и OData: практическое руководство по работе с REST-интерфейсом

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

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

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

Что такое OData в 1С и когда его использовать

OData (Open Data Protocol) — открытый протокол обмена данными поверх HTTP, разработанный Microsoft. В 1С он реализован как «стандартный интерфейс OData»: платформа автоматически генерирует REST-сервис на основе структуры конфигурации. Не нужно описывать методы, сериализацию и маршруты — всё это платформа делает сама.

Формат данных по умолчанию — Atom/XML, но добавлением заголовка Accept: application/json или параметра $format=json ответ переключается на JSON, что удобнее для большинства клиентов. Метаданные сервиса доступны по адресу .../odata/standard.odata/$metadata — там перечислены все опубликованные сущности и их поля.

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

Сравнение способов интеграции

Стандартный OData

Быстрый старт без кода, CRUD над объектами. Ограничение: нельзя встроить свою бизнес-логику, структура ответа жёстко привязана к метаданным.

HTTP-сервисы 1С

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

Планы обмена

Подходят для регулярной синхронизации между базами 1С с отслеживанием изменений. Избыточны для разовых запросов из внешних систем.

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

Публикация выполняется на веб-сервере — IIS или Apache. В конфигураторе откройте «Администрирование → Публикация на веб-сервере», укажите имя публикации, каталог и обязательно установите флажок «Публиковать стандартный интерфейс OData». После нажатия «Опубликовать» веб-сервер начнёт проксировать запросы к информационной базе.

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

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

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

Как читать данные: GET-запросы и параметры

Чтение выполняется обычными GET-запросами. Имя сущности строится по шаблону Тип_ИмяОбъекта: Catalog_Номенклатура, Document_РеализацияТоваровУслуг, InformationRegister_ЦеныНоменклатуры. Кириллица в именах допустима, но в URL её нужно кодировать.

Основные параметры запроса: $filter — отбор записей, $select — список полей, $top и $skip — постраничная выборка, $orderby — сортировка, $expand — разворачивание связанных данных (например, табличных частей документа). Пример выборки номенклатуры с фильтром по наименованию:

GET /base/odata/standard.odata/Catalog_Номенклатура?$filter=contains(Description,'Кабель')&$select=Ref_Key,Description,Артикул&$top=50&$format=json

Обращение к конкретной записи выполняется по ключу Ref_Key — это GUID объекта в виде guid'значение'. Табличные части документа запрашиваются через навигационное свойство: Document_РеализацияТоваровУслуг(guid'...')/Товары или сразу с $expand=Товары в основном запросе.

Как создавать и изменять данные

Создание объекта выполняется POST-запросом на набор сущностей с телом в формате JSON. Платформа вернёт созданный объект с присвоенным Ref_Key. Изменение — PATCH (или MERGE) на конкретный ключ, удаление — DELETE на ключ. При создании документа можно в одном запросе передать табличные части как вложенные массивы.

POST /base/odata/standard.odata/Catalog_Номенклатура
Content-Type: application/json
{
"Description": "Кабель ВВГ 3х2.5",
"Артикул": "KB-001"
}

Документы, созданные через OData, по умолчанию не проводятся — проведение выполняется отдельным POST-запросом на действие Post либо установкой свойства Posted при изменении. Учитывайте, что при записи через OData срабатывают обработчики событий объекта (ПриЗаписи, ОбработкаПроведения), поэтому вся прикладная валидация конфигурации сохраняется — это плюс для целостности данных.

Аутентификация и права доступа

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

Правильная практика — завести отдельного пользователя «Интеграция» с минимально необходимой ролью: только чтение нужных справочников, если внешняя система лишь забирает данные. Проверьте права заранее в разделе «Администрирование → Пользователи» и протестируйте запросы под этой учётной записью до передачи доступа внешней команде.

Контрольные точки

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

Открытие адреса /odata/standard.odata в браузере

Норма

После ввода логина отображается список сущностей (service document)

Тревожный признак

Ошибка 404 (OData не опубликован) или 500 (проблема с веб-расширением)

Запрос $metadata

Норма

Возвращается XML с описанием сущностей

Тревожный признак

Пустой ответ или ошибка аутентификации

Запрос с $top=1 к справочнику

Норма

JSON/XML с одной записью и полем Ref_Key

Тревожный признак

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

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

Стандартный OData в 1С имеет ряд ограничений. Не поддерживаются функции агрегации ($count работает ограниченно, group by отсутствует), пакетные запросы $batch в ранних версиях платформы недоступны, операции над виртуальными таблицами регистров не выполняются — остатки придётся получать через обороты или собственный HTTP-сервис. Некоторые типы данных (например, хранилище значений) сериализуются с ограничениями.

Из практики: самая частая проблема — ошибка 404 после публикации, вызванная тем, что не установлены модули расширения веб-сервера или не перезапущен IIS. Вторая по частоте — попытка фильтровать по полю, которого нет в $metadata, или использование русских имён без URL-кодирования. Третья — ожидание, что OData заменит полноценный API: как только требуется нестандартная логика (резервирование, расчёт скидок, сложные отборы), стандартного интерфейса уже не хватает.

FAQ: частые вопросы по OData в 1С

Можно ли использовать OData в файловой базе 1С?

Да, публикация работает и для файловых баз через веб-сервер. Однако файловый режим обрабатывает запросы последовательно, поэтому при параллельных обращениях от нескольких систем производительность заметно падает. Для постоянной интеграции рекомендуется клиент-серверный вариант.

Как получить данные в формате JSON вместо XML?

Добавьте к запросу параметр $format=json или заголовок Accept: application/json. Платформа вернёт ответ в JSON, что упрощает обработку в JavaScript, Python и других клиентах.

Почему запрос возвращает ошибку 404 после публикации?

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

Как ограничить, какие объекты доступны через OData?

В конфигураторе откройте свойства корня конфигурации и найдите параметр «Состав стандартного интерфейса OData». По умолчанию там полный список — оставьте только те справочники, документы и регистры, которые реально нужны внешней системе.

Срабатывают ли обработчики событий при записи через OData?

Да. При создании и изменении объектов через OData выполняются все прикладные обработчики — ПередЗаписью, ПриЗаписи, ОбработкаПроведения. Это гарантирует соблюдение бизнес-логики, но также означает, что запись может быть отклонена прикладным кодом с отказом.

Что делать, если стандартного OData не хватает?

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