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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Функция ПользовательУчетнойСистемы

Возвращает пользователя учетной системы.

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

• УчетнаяСистема – ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных – учетная система.

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

• СправочникСсылка.Пользователи

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

или

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

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

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