Как правильно создать документ и заполнить его табличную часть через OData REST API в 1С?

← На главную

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

Анализ проблемы: почему табличная часть остается пустой

Рассмотрим стандартную ситуацию: мы отправляем POST-запрос на адрес публикации сервиса OData, передавая в теле JSON-объект, структура которого полностью повторяет результат GET-запроса. На первый взгляд, всё логично: мы видим массив табличной части (например, "Товары"), заполняем его данными и ожидаем появления строк в 1С.

Проанализируем типичную ошибку. Часто разработчики пытаются явно передать Ref_Key (уникальный идентификатор GUID) как для самого документа, так и для каждой строки табличной части. В контексте OData 1С это приводит к тому, что система пытается найти уже существующего владельца для этих строк. Если документ еще не записан в базу, связь разрывается, и строки игнорируются, либо запрос завершается ошибкой. Рассмотрим, как этого избежать.

Решение №1: Использование механизма Deep Insert (Вложенная вставка)

Для того чтобы создать документ и его табличные части одним пакетом, используется механизм Deep Insert. Основное правило здесь — минимизация избыточных идентификаторов. Выясним на практике, какие поля стоит исключить.

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

Посмотрим на пример корректного JSON-тела для создания документа СчетНаОплатуПокупателю:


{
    "Posted": false,
    "Организация_Key": "59d36f49-3ee9-11e8-a725-000c290bd191",
    "Контрагент_Key": "befd037b-3eec-11e8-a725-000c290bd191",
    "ВалютаДокумента_Key": "4cf66526-3ee7-11e8-a725-000c290bd191",
    "Товары": [
        {
            "LineNumber": "1",
            "Номенклатура_Key": "6a8c095a-6005-11e8-a2ed-000c290bd191",
            "Содержание": "Услуги по настройке ПО",
            "Количество": 1,
            "Цена": 5000,
            "Сумма": 5000,
            "СтавкаНДС": "БезНДС",
            "СуммаНДС": 0
        }
    ]
}

Обратите внимание: в массиве Товары отсутствуют ссылки на владельца. 1С сама поймет, что эти строки относятся к создаваемому документу.

Решение №2: Работа с существующим документом (PATCH и PUT)

Если нам необходимо заполнить табличную часть уже существующего документа, мы используем метод PATCH. Однако здесь возникает важный нюанс: 1С требует соблюдения механизма оптимистической блокировки.

Разберем по шагам, что нужно сделать:

Сначала необходимо получить текущую версию объекта (DataVersion или ETag) с помощью GET-запроса.
При отправке PATCH-запроса обязательно добавьте HTTP-заголовок If-Match, в который поместите значение DataVersion. Без этого заголовка сервер часто возвращает ошибку "Использованный HTTP метод запрещен в данном контексте".
Помните, что при использовании PATCH вы обновляете только переданные поля. Однако работа с табличными частями через PATCH может быть ограничена в зависимости от версии платформы. Если вложенное обновление не срабатывает, рассмотрите возможность полной перезаписи объекта через PUT.

Важные технические нюансы и типы данных

Проанализируем специфические требования 1С к формату данных в JSON, которые часто становятся причиной "тихих" ошибок (когда запрос проходит, но данные не записываются):

Тип поля LineNumber: В метаданных 1С номер строки — это число. Но в некоторых версиях платформы через OData он может ожидаться как строка (например, "1") или как число (1). Если табличная часть не заполняется, попробуйте изменить формат передачи этого поля.
Перечисления (Enums): Значения ссылочных типов для перечислений передаются в виде строкового представления имени значения, как оно задано в конфигураторе (например, "БезНДС" или "Товар").
GUID и пустые ссылки: Если реквизит не заполнен, лучше передать "00000000-0000-0000-0000-000000000000", чем просто опускать поле, особенно если это обязательный реквизит для типовой конфигурации (например, Склад_Key в БП 3.0).

Проведение документа после создания

Стоит помнить, что отправка "Posted": true в POST-запросе не всегда гарантирует проведение документа. В 1С проведение — это отдельная процедура, запускающая расчеты по регистрам. Правильным подходом считается использование специализированных команд OData.

После успешного создания документа (получения Ref_Key), выполните следующий POST-запрос:

URL/odata/standard.odata/Document_ИмяДокумента(guid'ваш-guid-тут')/Post

Это инициирует штатное проведение документа на стороне сервера 1С.

Настройка прав доступа и состава OData

Если все JSON-структуры верны, но данные всё равно не попадают в базу, проверьте настройки в конфигураторе:

Откройте свойства конфигурации, вкладка "Прочие", кнопка "Состав стандартного интерфейса OData".
Убедитесь, что ваш документ и — что критически важно — его табличные части отмечены галочками.
Проверьте права пользователя. Для записи документа через OData пользователю требуются права не только на "Добавление" и "Изменение", но и на соответствующие операции с табличными частями.

Таким образом, успех при заполнении табличных частей в 1С через OData зависит от правильного использования Deep Insert, исключения лишних Ref_Key и строгого соблюдения типов данных JSON. Используя эти рекомендации, вы сможете наладить стабильный обмен данными между любой внешней системой и 1С.