Как создать заказ клиента в 1С:Комплексная автоматизация через OData и получить его идентификатор?

Программист 1С v8.3 (Управляемые формы) 1С:Комплексная автоматизация Управленческий учет IT и автоматизация бизнеса
← На главную

В современной практике интеграции внешних систем с 1С использование протокола OData (автоматического REST-интерфейса) является одним из наиболее эффективных способов. Рассмотрим задачу создания документа ЗаказКлиента в конфигурации «1С:Комплексная автоматизация» (КА). Мы разберем весь цикл: от подготовки базы до получения уникального идентификатора (GUID) созданного объекта и его последующего проведения.

Шаг 1. Подготовка системы и проверка метаданных

Прежде чем отправлять запросы, нам необходимо убедиться, что база 1С готова к приему данных. Проанализируем настройки доступа. Для работы через OData у пользователя, под чьим именем будет выполняться запрос, должна быть установлена роль «Удаленный доступ через OData» (Remote access via OData). Кроме того, интерфейс должен быть включен в меню «Администрирование — Синхронизация данных».

Важно помнить, что в разных конфигурациях имена документов могут отличаться. В актуальных релизах «1С:КА 2» документ «Заказ покупателя» называется ЗаказКлиента. Чтобы точно определить внутреннее имя сущности, разберем формат получения метаданных. Перейдем по адресу:


http://server/base/odata/standard.odata/$metadata

В полученном XML-файле найдем описание EntityType Name="Document_ЗаказКлиента". Это и будет наш базовый адрес для POST-запросов.

Шаг 2. Настройка авторизации и заголовков запроса

Для взаимодействия с 1С обычно используется Basic Authentication. Логин и пароль пользователя кодируются в формат Base64 и передаются в заголовке Authorization. При работе с JSON-форматом (который гораздо легче и удобнее, чем XML) обязательно укажем следующие HTTP-заголовки:

Адрес ресурса для создания документа будет выглядеть следующим образом:


http://имя_сервера/имя_базы/odata/standard.odata/Document_ЗаказКлиента?$format=json

Шаг 3. Формирование структуры данных JSON

Выясним причину, по которой новички часто совершают ошибки при заполнении ссылочных полей. В 1С справочники и документы — это ссылочные типы. Для их передачи в OData используется суффикс _Key. Например, вместо передачи названия организации в поле Организация, мы должны передать GUID этой организации в поле Организация_Key.

Рассмотрим пример структуры JSON для создания заказа клиента с одной строкой в табличной части «Товары»:


{
  "Date": "2023-10-25T14:30:00",
  "Организация_Key": "592a870d-3843-11e9-80d4-00155d01f20b",
  "Partner_Key": "782b120a-4122-11e9-80d8-00155d01f20b",
  "Контрагент_Key": "782b120a-4122-11e9-80d8-00155d01f20b",
  "Валюта_Key": "25f56470-3831-11e9-80d4-00155d01f20b",
  "Склад_Key": "8f2e220c-3844-11e9-80d4-00155d01f20b",
  "Товары": [
    {
      "LineNumber": "1",
      "Номенклатура_Key": "a2b1c3d4-e5f6-7890-abcd-ef1234567890",
      "Количество": 10,
      "Цена": 1500,
      "Сумма": 15000,
      "СтавкаНДС": "НДС20"
    }
  ]
}

Обратите внимание: перечисления (например, СтавкаНДС) передаются как строковые значения. Поля с датой должны соответствовать формату ISO 8601. Хотя 1С может сама нумеровать строки, мы рекомендуем явно указывать LineNumber для обеспечения стабильности при обработке табличных частей.

Шаг 4. Обработка ответа: получение GUID и обработка ошибок

После отправки POST-запроса проанализируем ответ сервера. Если всё прошло успешно, 1С вернет HTTP-статус 201 Created. В теле ответа придет полная структура созданного документа в формате JSON. Самым важным полем для нас является Ref_Key — это и есть уникальный идентификатор (GUID) созданного заказа. Его необходимо сохранить во внешней системе для последующей связи объектов.

Если же произошла ошибка (например, не заполнено обязательное поле или передан неверный GUID справочника), сервер вернет статус 400 Bad Request или 500 Internal Server Error. В теле ответа будет содержаться объект error, который поможет нам выяснить причину:


{
  "error": {
    "code": "-1",
    "message": {
      "lang": "ru",
      "value": "Поле 'Организация' не заполнено"
    }
  }
}

Шаг 5. Проведение документа

Важный нюанс работы с OData заключается в том, что простой POST-запрос создает документ, но не проводит его (он остается только записанным). Если бизнес-логика требует проведения документа сразу после создания, нам нужно выполнить второй запрос — вызвать метод Post.

Рассмотрим алгоритм действий: используем полученный ранее Ref_Key и отправим POST-запрос на специальный URL. Проанализируем пример запроса для проведения документа:


POST /odata/standard.odata/Document_ЗаказКлиента(guid'ваш-гуид-из-Ref_Key')/Post?PostingMode=Operational

Параметр PostingMode=Operational указывает на оперативное проведение. Если документ успешно проведется, сервер вернет статус 200 OK. Если в модуле проведения 1С сработают проверки (например, нехватка остатков на складе), вы получите подробное описание ошибки в формате JSON, аналогично ошибкам записи.

Особенности и ограничения

Разберем важные моменты, которые следует учитывать при проектировании интеграции через OData:

  1. Бизнес-логика форм: Помните, что при записи через OData код, написанный в «Модуле формы» 1С, не исполняется. Выполняются только обработчики «ПередЗаписью» и «ПриЗаписи» в «Модуле объекта». Поэтому все расчеты (суммы НДС, итоговые суммы по документу) лучше рассчитывать на стороне внешней системы и передавать в JSON-пакете готовыми значениями.
  2. Производительность: OData — это мощный инструмент, но при создании сотен заказов в минуту стоит рассмотреть возможность пакетной передачи данных или использования специализированных HTTP-сервисов, написанных вручную внутри 1С.
  3. Предварительная загрузка НСИ: Чтобы заполнить Partner_Key или Номенклатура_Key, ваша внешняя система должна заранее знать GUID этих объектов в базе 1С. Обычно это решается предварительной синхронизацией справочников через те же GET-запросы OData.

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

← На главную