Интеграция объектов: программный интерфейс для разработчика 1С

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

1. Получатель запрашивает для себя изменения
2. Получатель проверяет готовность запрошенных данных
3. Получатель загружает данные к себе
4. Получатель обрабатывает данные и подтверждает, что изменения загружены и обработаны.

1. Отправитель формирует пакет данных и отправляет файл данных для обработки
2. Отправитель ожидает завершения обработки данных

1. Приложение отправляет оповещение в приложение провайдера при изменении данных
2. Приложение провайдера забирает изменения
3. Приложение провайдера подтверждает изменения

В прикладном решении может быть реализован механизм обработки команд от внешней учетной системы. 

Примеры команд:

• Создание объектов (документов, справочников)
• Выполнение расчетов

Если в процессе выполнения команды был создан объект, то информация о нем будет возвращена в результате на 2-м шаге.

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

• Пароль (Строка) - пароль аутентификации в сервисе приема оповещений (используется при basic-аутентификации)
• ПарольСертификата (Строка) - пароль сертификата (используется, если задано свойство ИспользоватьСертификат);
• ДанныеСертификата (ДвоичныеДанные) - двоичные данные сертификата в Base64 (используется, если задано свойство ИспользоватьСертификат)
• КлючПодписи (Строка) - секретное слово, для подписи отправляемых данных. Подпись выполняется с помощью алгоритма HMACSHA256.

Также этот тип определяет:

• разрез хранения объектов к отправке в регистре сведений ОбъектыКОтправке.
• хранение настроек учетных систем в регистре сведений НастройкиУчетныхСистем.

В регистре сведений НастройкиУчетныхСистем хранятся настройки для определения учетной системы и для отправки оповещений.

• Пользователь (СправочникСсылка.Пользователи) - для определения учетной системы по авторизованному пользователю при обращении к API.
• ОповещатьОбИзменениях (Булево) - признак использования оповещений при создании/изменении данных в приложении
• АдресСервиса (Строка) - адрес сервиса приема оповещений об изменениях
• СпособАутентификации (ПеречислениеСсылка.СпособыАутентификации) - способ аутентификации в сервисе приема оповещений
• Логин (Строка) - логин аутентификации в сервисе приема оповещений (используется при basic-аутентификации)
• ИспользоватьСертификат (Булево) - признак использования сертификата при установке соединения с сервисом приема оповещений
• ИмяСертификата (Строка) - имя файла сертификата
• ПодписыватьДанные (Булево) - признак использования подписи данных при отправке их в сервис приема оповещений

Методы интерфейса объектного хранилища для DataTransfer.

1. Описание - метод не поддерживается
2. Данные - метод не поддерживается
3. Загрузить - основной метод работы с объектным хранилищем интеграции объектов.

Поддерживаются идентификаторы данных для метода Загрузить:

1. setup - для установки настроек учетной системы
2. get - для получения данных из приложения
3. post - для добавления данных в приложение
4. confirm - для подтверждения получения данных от приложения
5. execute - для отправки команды на выполнение действий

Находятся в общем модуле ИнтеграцияОбъектовОбластейДанных.

Процедура ДобавитьОбъектКОтправке 

Позволяет добавить объект к отправке во внешнюю учетную систему.
Параметры метода:

• УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
• ИдентификаторОбъекта - Строка(50) - идентификатор объекта, должен соответствовать требованиям к именованию файлов операционной системы.
• Обработчик - Строка(50) - идентификатор обработчика объекта.
• ДанныеОбъекта - ДвоичныеДанные - данные объекта к отпрвке (если не указано, данные будут запрошены перед отправкой).

Процедура УдалитьОбъектКОтправке 

Позволяет удалить объект из списка объектов к отправке в учетную систему.
Параметры метода:

• УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
• ИдентификаторОбъекта - Строка(50) - идентификатор объекта
• Обработчик - Строка(50) - идентификатор обработчика объекта.

Функция ОповеститьОбИзмененииОбъекта

Выполняет оповещение внешней учетной системы об изменении объекта в приложении в соответствие с настройками оповещения. При использовании оповещений нужно убедиться, что данные объекта подготовлены заранее. Если данные не подготовлены, отправка оповещения не выполняется.
Параметры метода:

• УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
• ИдентификаторОбъекта - Строка(50) - идентификатор объекта
• ВызыватьИсключение - Булево - признак вызова исключения при неудачной отправке оповещения.

Функция Настройки

Возвращает настройки учетной системы.
Параметры метода:

• УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
• КлючиНастроек - Строка, Массив - ключи настроек, по которым нужно вернуть значения.

Функция НовыйРезультатыВыполненияКоманды 

Возвращает шаблон для помещения результатов выполнения команды.

Возвращаемое значение:

• ТаблицаЗначений - шаблон выполнения команды для возврата результатов. Содержит колонки:
  • ИдентификаторОбъекта - Строка(50) - идентификатор объекта.
  • Обработчик - Строка(50) - идентификатор обработчика.

Методы, возвращающие коды возврата по имени

Могут использоваться в коде учетной системы при выполнении обработки или подготовки данных, а также при обработке подтверждений.
Находятся в общем модуле ИнтеграцияОбъектовОбластейДанныхСловарь.

• КодВозвратаОшибкаДанных - возвращает число 10400
• КодВозвратаВнутренняяОшибка - возвращает число 10500
• КодВозвратаВыполненоСПредупреждениями - возвращает число 10240
• КодВозвратаВыполнено - возвращает число 10200
• КодВозвратаНеНайдено - возвращает число 10404

Возвращаемое значение

• Число - стандартный код возврата по имени метода

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

• ОбластьДанныхВспомогательныеДанные = Автоматически
• ОбластьДанныхОсновныеДанные = Автоматически

В модуле менеджера объекта должен быть реализован программный интерфейс, включающий методы, приведенные ниже.

Процедура УстановитьНастройки

Предназначена для обработки устанавливаемых настроек учетной системы, полученных от внешней учетной системы.
Параметры:

• УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных
• ПотокДанных - ФайловыйПоток, ПотокВПамяти - данные настроек (передаются в формате json)
• КодВозврата - Число - код возврата обработчика установки настроек (по умолчанию - 10200).
• Ошибка - Булево - признак ошибки (по умолчанию - Ложь)
• СообщениеОбОшибке - Строка - подробности ошибки (по умолчанию не заполнено).
• СтандартнаяОбработка - Булево - признак стандартной обработки.

Процедура УстановитьПраваДоступа

(при использовании БТС версии начиная с 2.0.1.6)

Устанавливает права пользователя, от имени которого обращается внешняя учетная система.

Параметры метода:

• УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
• Пользователь - СправочникСсылка.Пользователи - пользователь, от имени которого обращается внешняя учетная система.

Установка прав доступа должна быть определена прикладным разработчиком в соответствии с используемой ролевой моделью.
Для работы интеграции объектов пользователю нужно предоставить роль УдаленныйДоступПередачаДанных.

Функция ТипУчетнойСистемы

Возвращает идентификатор типа учетной системы для определения менеджера объекта, если ссылки на учетную систему с пользователем обратившейся внешней системы еще не существует.

Функция ДанныеОбъекта

Возвращает двоичные данныеобъекта, которые будут переданы в составе zip-архива во внешнюю учетную систему.
Параметры:

• УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных
• ИдентификаторОбъекта - Строка(50) - идентификатор объекта.
• Обработчик - Строка(50) - обработчик данных объекта.

Возвращаемое значение:

• ДвоичныеДанные - данные объекта.

Процедура ОбработатьПодтверждения

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

• УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных
• Подтверждения - Соответствие
  • Ключ - Строка - это идентификатор объекта
  • Значение - Структура
    • Версия - Строка - версия объекта
    • КодВозврата - Число - код возврата, определяется во внешней учетной системе. Рекомендуемые коды возврата см. модуле ИнтеграцияОбъектовОбластейДанныхСловарь
    • Ошибка - Булево - признак ошибки (по умолчанию - Ложь)
    • СообщениеОбОшибке - Строка - подробности ошибки (по умолчанию не заполнено)
• СтандартнаяОбработка - Булево - признак стандартной обработки. Если Ложь, то у обработанные объекты не будут удалены из списка объектов к отправке.

Функция ОбработатьДанные

Предназначена для обработки данных объектов, получаемых от внешней учетной системы.
Параметры:

• УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
• ИдентификаторОбъекта - Строка(50) - идентификатор объекта для обработка
• ПотокДанных - ФайловыйПоток, ПотокВПамяти - данные объекта
• Обработчик - Строка - идентификатор обработчика
• КодВозврата - Число - код возврата обработчика (по умолчанию - 10200)
• Ошибка - Булево - признак ошибки (по умолчанию - Ложь)
• СообщениеОбОшибке - Строка - подробности ошибки (по умолчанию не заполнено).

Функция ВыполнитьКоманду

Обработчик выполнения команды от учетной системы.

Параметры:

• УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
• ПотокДанныхКоманды - ФайловыйПоток, ПотокВПамяти - данные команды.
• КодВозврата - Число - код возврата обработчика (по умолчанию - 10200)
• Ошибка - Булево - признак ошибки (по умолчанию - Ложь)
• СообщениеОбОшибке - Строка - подробности ошибки (по умолчанию не заполнено).

Возвращаемое значение:

• Неопределено - если не подразумевается создание объектов, или в процессе выполнения произошла ошибка.

или

• ТаблицаЗначений - результаты выполнения команды, информация о созданных или измененных объектах

  (см. ИнтеграцияОбъектовОбластейДанных.НовыйРезультатыВыполненияКоманды).

Собственные прикладные методы

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