Как передать значение перечисления в POST-запросе 1С OData

Работа с протоколом OData в 1С часто вызывает вопросы у разработчиков, особенно когда дело касается специфических типов данных, таких как перечисления (Enums). В отличие от справочников или документов, перечисления не имеют уникального идентификатора (UUID) в привычном понимании при передаче через REST-интерфейс. В этой статье мы подробно разберем, как правильно передавать значения перечислений, почему они могут «сбрасываться» после записи и на что важно обратить внимание при формировании POST-запроса.

Разбор формата передачи значения перечисления

Рассмотрим ситуацию: нам необходимо создать документ в базе-приемнике и установить в его табличной части определенную ставку НДС. Ставка НДС в 1С почти всегда является Перечислением. Первая ошибка, с которой сталкиваются разработчики — попытка передать синоним значения (например, "10%" или "Без НДС") или его порядковый номер в списке.

Проанализируем механику работы OData: интерфейс ожидает не синоним, а внутреннее имя (Идентификатор) значения перечисления, которое задано в конфигураторе. Например, если в конфигураторе значение называется НДС10, а на экране пользователь видит "10%", то передавать нужно именно НДС10.

При использовании формата XML (AtomPub) передача значения будет выглядеть следующим образом:

<d:СтавкаНДС>НДС10</d:СтавкаНДС>

Если же вы работаете с форматом JSON, значение передается как обычная строка:

"СтавкаНДС": "НДС10"

Выясняем правильные имена через метаданные

Если вы не знаете точного имени значения перечисления в конкретной конфигурации (например, в УТ и УПП они могут называться по-разному), мы рекомендуем обратиться к метаданным самой базы через OData. Для этого выполним GET-запрос:

.../odata/standard.odata/$metadata

В полученном ответе найдем раздел EnumType. В нем будут перечислены все доступные значения для каждого перечисления. Рассмотрим пример структуры для СтавкиНДС:

<EnumType Name="Перечисление.СтавкиНДС">
    <Member Name="НДС10"/>
    <Member Name="НДС18"/>
    <Member Name="БезНДС"/>
</EnumType>

Именно значение из атрибута Name является эталонным для передачи в запросе POST.

Проблема «сброса» значения и зависимые реквизиты

Часто возникает ситуация, когда запрос проходит успешно (HTTP 201 Created), но в созданном документе значение перечисления оказывается пустым или установленным в значение по умолчанию (например, "Без НДС"), хотя в запросе было передано НДС10. Разберем причину этого поведения.

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

Выясним причину на конкретном примере. В документах часто ставка НДС напрямую зависит от реквизита УчитыватьНДС. Если вы передаете ставку, но не передаете флаг УчитыватьНДС (или передаете его как false), внутренняя логика документа при записи может автоматически очистить ставку НДС, считая ее неактуальной для данного режима налогообложения.

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

• УчитыватьНДС
• ЦенаВключаетНДС
• НалогообложениеНДС

Работа с составными типами данных

Иногда реквизит может иметь составной тип (например, ЛюбаяСсылка или объединение справочника и перечисления). В этом случае простой передачи строки будет недостаточно, так как система не поймет, к какому типу относится значение НДС10.

Проанализируем ситуацию с составным типом в формате JSON. Для корректной обработки необходимо использовать суффикс _type, чтобы явно указать тип передаваемого значения:

"Реквизит_type": "StandardOData.Перечисление.СтавкиНДС",
"Реквизит": "НДС10"

Без указания типа система может вернуть ошибку о несоответствии параметров или проигнорировать поле.

Пошаговый алгоритм успешного POST-запроса с перечислением

1. Выполним GET-запрос к метаданным ($metadata) или к самому перечислению (.../standard.odata/Перечисление_СтавкиНДС), чтобы получить точный список имен (Name).
2. В теле POST-запроса укажем значение перечисления в строковом формате (именно идентификатор, а не синоним).
3. Проверим наличие всех зависимых реквизитов в объекте. Посмотрим в конфигураторе код модуля объекта (процедуру ПередЗаписью или ПриЗаписи), чтобы понять, какие условия могут приводить к очистке поля.
4. Если реквизит составной — добавим поле с суффиксом _type.
5. Отправим запрос и проверим результат. Если значение все равно не устанавливается, попробуем сначала выполнить GET-запрос существующего аналогичного документа, чтобы посмотреть, в каком именно формате 1С сама отдает эти данные.

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